Skip to content

update planet orders request arguments #805

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.

Sign up for GitHub

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

Merged
merged 5 commits into from
Dec 1, 2022
Merged

update planet orders request arguments #805

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c4a67f9
planet orders request arguments changed to ids being the only argumen…
jreiberkyle Dec 1, 2022
31b76db
update docs to planet orders request arg structure
jreiberkyle Dec 1, 2022
20c0eae
Merge branch 'main' into requests-args-736
jreiberkyle Dec 1, 2022
9a7c41e
Update docs/cli/cli-orders.md
jreiberkyle Dec 1, 2022
415bd33
tiny doc fixes
jreiberkyle Dec 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 28 additions & 25 deletions docs/cli/cli-orders.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,19 +107,19 @@ If you don't have access to PlanetScope data then replace PSScene with SkySatCol
Then make the following call:

```console
planet orders request PSScene visual --name 'My First Order' --id 20220605_124027_64_242b
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'My First Order' 20220605_124027_64_242b
```

Running the above command should output the JSON needed to create an order:

```json
{"name": "My First Order", "products": [{"item_ids": ["20220605_124027_64_242b"], "item_type": "PSScene", "product_bundle": "analytic_sr_udm2"}]}
{"name": "My First Order", "products": [{"item_ids": ["20220605_124027_64_242b"], "item_type": "PSScene", "product_bundle": "analytic_sr_udm2"}], "metadata": {"stac": {}}}
```

You can also use `jq` here to make it a bit more readable:

```console
planet orders request PSScene analytic_sr_udm2 --name 'My First Order' --id 20220605_124027_64_242b | jq
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'My First Order' 20220605_124027_64_242b | jq
```

```json
Expand All @@ -133,7 +133,10 @@ planet orders request PSScene analytic_sr_udm2 --name 'My First Order' --id 2022
"item_type": "PSScene",
"product_bundle": "analytic_sr_udm2"
}
]
],
"metadata": {
"stac": {}
}
}
```

Expand All @@ -143,7 +146,7 @@ The above command just prints out the necessary JSON to create an order. To actu
save the output into a file:

```console
planet orders request PSScene analytic_sr_udm2 --name "My First Order" --id 20220605_124027_64_242b \
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name "My First Order" 20220605_124027_64_242b \
> request-1.json
```

Expand Down Expand Up @@ -200,8 +203,8 @@ passing the output of the `orders request` command directly to be the input of t
command:

```console
planet orders request PSScene analytic_sr_udm2 --name 'Two Item Order' \
--id 20220605_124027_64_242b,20220605_124025_34_242b | planet orders create -
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Two Item Order' \
20220605_124027_64_242b,20220605_124025_34_242b | planet orders create -
```

The Planet CLI is designed to work well with piping, as it aims at small commands that can be
Expand Down Expand Up @@ -357,8 +360,8 @@ You can move that geometry to your current directory and use the following comma
tweak the geometry.geojson to refer to where you downloaded it.

```console
planet orders request PSScene analytic_sr_udm2 --clip geometry.geojson --name clipped-geom \
--id 20220605_124027_64_242b | planet orders create -
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --clip geometry.geojson --name clipped-geom \
20220605_124027_64_242b | planet orders create -
```

### Additional Tools
Expand Down Expand Up @@ -406,8 +409,8 @@ Example: `tools.json`
Ordering two scenes is easy, just add another id:

```console
planet orders request PSScene analytic_sr_udm2 --name 'Two Scenes' \
--id 20220605_124027_64_242b,20220605_124025_34_242b | planet orders create -
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Two Scenes' \
20220605_124027_64_242b,20220605_124025_34_242b | planet orders create -
```

And then you can composite them together, using the 'tools' json. You can
Expand All @@ -426,8 +429,8 @@ Once you've got it saved you call the `--tools` flag to refer to the JSON file,
can pipe that to `orders create`.

```console
planet orders request PSScene analytic_sr_udm2 --name 'Two Scenes Composited' \
--id 20220605_124027_64_242b,20220605_124025_34_242b --no-stac --tools tools-composite.json | planet orders create -
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Two Scenes Composited' \
20220605_124027_64_242b,20220605_124025_34_242b --no-stac --tools tools-composite.json | planet orders create -
```

Note that we add the `--no-stac` option as [STAC Metadata](#stac-metadata) is not yet supported by the composite
Expand All @@ -452,8 +455,8 @@ as COG in the file format tool.
The following command just shows the output with [tools-cog.json](https://raw.githubusercontent.com/planetlabs/planet-client-python/main/docs/cli/request-json/tools-cog.json):

```console
planet orders request PSScene analytic_sr_udm2 --name 'COG Order' \
--id 20220605_124027_64_242b,20220605_124025_34_242b --tools tools-cog.json
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'COG Order' \
20220605_124027_64_242b,20220605_124025_34_242b --tools tools-cog.json
```

As shown above you can also pipe that output directly in to `orders create`.
Expand Down Expand Up @@ -504,16 +507,16 @@ so you can just use the [following json](https://raw.githubusercontent.com/plane
```

```console
planet orders request PSScene analytic_sr_udm2 --no-stac --name 'Two Scenes Clipped and Composited' \
--id 20220605_124027_64_242b,20220605_124025_34_242b --tools tools-clip-composite.json | planet orders create -
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --no-stac --name 'Two Scenes Clipped and Composited' \
20220605_124027_64_242b,20220605_124025_34_242b --tools tools-clip-composite.json | planet orders create -
```

One cool little trick is that you can even stream in the JSON directly with `curl`, piping it into the request:

```console
curl -s https://raw.githubusercontent.com/planetlabs/planet-client-python/main/docs/cli/request-json/tools-clip-composite.json \
| planet orders request PSScene analytic_sr_udm2 --name 'Streaming Clip & Composite' \
--id 20220605_124027_64_242b,20220605_124025_34_242b --tools - | planet orders create -
| planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Streaming Clip & Composite' \
20220605_124027_64_242b,20220605_124025_34_242b --tools - | planet orders create -
```

### Harmonize
Expand All @@ -533,7 +536,7 @@ The harmonize tool allows you to compare data to different generations of satell
You may create an order request by calling [`tools-harmonize.json`](https://raw.githubusercontent.com/planetlabs/planet-client-python/main/docs/cli/request-json/tools-harmonize.json) with `--tools`.

```console
planet orders request psscene analytic_sr_udm2 --name 'Harmonized data' --id 20200925_161029_69_2223 --tools tools-harmonize.json
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Harmonized data' 20200925_161029_69_2223 --tools tools-harmonize.json
```

## More options
Expand Down Expand Up @@ -668,9 +671,9 @@ image that was published:


```console
planet orders request SkySatCollect analytic --name 'SkySat Latest' \
--id `planet data filter | planet data search SkySatCollect --sort 'acquired desc' --limit 1 - | jq -r .id` \
| planet orders create -
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 orders create -
```

Or get the 5 latest cloud free images in an area and create an order that clips to that area, using
Expand All @@ -679,8 +682,8 @@ 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/.$//'`
planet orders request PSScene analytic_sr_udm2 --name 'Clipped Scenes' \
--id $ids --clip geometry.geojson | planet orders create -
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Clipped Scenes' \
$ids --clip geometry.geojson | planet orders create -
```

This one uses some advanced unix capabilities like `sed` and `tr`, along with unix variables, so more
Expand Down
33 changes: 17 additions & 16 deletions planet/cli/orders.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,22 +225,21 @@ async def create(ctx, request: str, pretty):
@click.pass_context
@translate_exceptions
@coro
@click.argument('item_type',
metavar='ITEM_TYPE',
type=click.Choice(planet.specs.get_item_types(),
case_sensitive=False))
@click.argument('bundle',
metavar='BUNDLE',
type=click.Choice(planet.specs.get_product_bundles(),
case_sensitive=False))
@click.argument('ids', metavar='IDS', type=types.CommaSeparatedString())
@click.option('--item-type',
required=True,
help='Item type for requested item ids.',
type=click.Choice(planet.specs.get_item_types(),
case_sensitive=False))
@click.option('--bundle',
required=True,
help='Asset type for the item.',
type=click.Choice(planet.specs.get_product_bundles(),
case_sensitive=False))
@click.option('--name',
required=True,
help='Order name. Does not need to be unique.',
type=click.STRING)
@click.option('--id',
help='One or more comma-separated item IDs.',
type=types.CommaSeparatedString(),
required=True)
@click.option('--clip',
type=types.JSON(),
help="""Clip feature GeoJSON. Can be a json string, filename,
Expand Down Expand Up @@ -270,7 +269,7 @@ async def request(ctx,
item_type,
bundle,
name,
id,
ids,
clip,
tools,
email,
Expand All @@ -280,11 +279,13 @@ async def request(ctx,
"""Generate an order request.

This command provides support for building an order description used
in creating an order. It outputs the order request, optionally pretty-
printed.
in creating an order. It outputs the order request, optionally
pretty-printed.

IDs is one or more comma-separated item IDs.
"""
try:
product = planet.order_request.product(id, bundle, item_type)
product = planet.order_request.product(ids, bundle, item_type)
except planet.specs.SpecificationException as e:
raise click.BadParameter(e)

Expand Down
81 changes: 40 additions & 41 deletions tests/integration/test_orders_cli.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -461,10 +461,10 @@ def test_cli_orders_request_basic_success(expected_ids,
stac_json):
result = invoke([
'request',
'PSOrthoTile',
'analytic',
'--item-type=PSOrthoTile',
'--bundle=analytic',
'--name=test',
f'--id={id_string}',
id_string,
])
assert not result.exception

Expand All @@ -485,45 +485,44 @@ def test_cli_orders_request_basic_success(expected_ids,
def test_cli_orders_request_item_type_invalid(invoke):
result = invoke([
'request',
'invalid'
'analytic',
'--item-type=invalid'
'--bundle=analytic',
'--name=test',
'--id=4500474_2133707_2021-05-20_2419',
'4500474_2133707_2021-05-20_2419',
])
assert result.exit_code == 2
error_msg = "Usage: main orders request [OPTIONS] ITEM_TYPE BUNDLE"
assert error_msg in result.output


def test_cli_orders_request_product_bundle_invalid(invoke):
result = invoke([
'request',
'PSScene'
'invalid',
'--item-type=PSScene'
'--bundle=invalid',
'--name=test',
'--id=4500474_2133707_2021-05-20_2419',
'4500474_2133707_2021-05-20_2419',
])
assert result.exit_code == 2
error_msg = "Usage: main orders request [OPTIONS] ITEM_TYPE BUNDLE"
assert error_msg in result.output


def test_cli_orders_request_product_bundle_incompatible(invoke):
result = invoke([
'request',
'PSScene',
'analytic',
'--item-type=PSScene',
'--bundle=analytic',
'--name=test',
'--id=4500474_2133707_2021-05-20_2419',
'4500474_2133707_2021-05-20_2419',
])
assert result.exit_code == 2
error_msg = "Usage: main orders request [OPTIONS] ITEM_TYPE BUNDLE"
assert error_msg in result.output


def test_cli_orders_request_id_empty(invoke):
result = invoke(
['request', 'PSOrthoTile', 'analytic', '--name=test', '--id='])
result = invoke([
'request',
'--item-type=PSOrthoTile',
'--bundle=analytic',
'--name=test',
''
])
assert result.exit_code == 2
assert 'Entry cannot be an empty string.' in result.output

Expand All @@ -541,10 +540,10 @@ def test_cli_orders_request_clip_success(geom_fixture,

result = invoke([
'request',
'PSOrthoTile',
'analytic',
'--item-type=PSOrthoTile',
'--bundle=analytic',
'--name=test',
'--id=4500474_2133707_2021-05-20_2419',
'4500474_2133707_2021-05-20_2419',
f'--clip={json.dumps(geom)}',
])
assert result.exit_code == 0
Expand All @@ -571,10 +570,10 @@ def test_cli_orders_request_clip_success(geom_fixture,
def test_cli_orders_request_clip_invalid_geometry(invoke, point_geom_geojson):
result = invoke([
'request',
'PSOrthoTile',
'analytic',
'--item-type=PSOrthoTile',
'--bundle=analytic',
'--name=test',
'--id=4500474_2133707_2021-05-20_2419',
'4500474_2133707_2021-05-20_2419',
f'--clip={json.dumps(point_geom_geojson)}'
])
assert result.exit_code == 2
Expand All @@ -588,10 +587,10 @@ def test_cli_orders_request_both_clip_and_tools(invoke, geom_geojson):
# option values are valid json
result = invoke([
'request',
'PSOrthoTile',
'analytic',
'--item-type=PSOrthoTile',
'--bundle=analytic',
'--name=test',
'--id=4500474_2133707_2021-05-20_2419',
'4500474_2133707_2021-05-20_2419',
f'--clip={json.dumps(geom_geojson)}',
f'--tools={json.dumps(geom_geojson)}'
])
Expand All @@ -613,10 +612,10 @@ def test_cli_orders_request_cloudconfig(invoke, stac_json):

result = invoke([
'request',
'PSOrthoTile',
'analytic',
'--item-type=PSOrthoTile',
'--bundle=analytic',
'--name=test',
'--id=4500474_2133707_2021-05-20_2419',
'4500474_2133707_2021-05-20_2419',
f'--cloudconfig={json.dumps(config_json)}',
])
assert result.exit_code == 0
Expand All @@ -640,10 +639,10 @@ def test_cli_orders_request_cloudconfig(invoke, stac_json):
def test_cli_orders_request_email(invoke, stac_json):
result = invoke([
'request',
'PSOrthoTile',
'analytic',
'--item-type=PSOrthoTile',
'--bundle=analytic',
'--name=test',
'--id=4500474_2133707_2021-05-20_2419',
'4500474_2133707_2021-05-20_2419',
'--email'
])
assert result.exit_code == 0
Expand Down Expand Up @@ -671,10 +670,10 @@ def test_cli_orders_request_tools(invoke, geom_geojson, stac_json):

result = invoke([
'request',
'PSOrthoTile',
'analytic',
'--item-type=PSOrthoTile',
'--bundle=analytic',
'--name=test',
'--id=4500474_2133707_2021-05-20_2419',
'4500474_2133707_2021-05-20_2419',
f'--tools={json.dumps(tools_json)}'
])

Expand All @@ -699,10 +698,10 @@ def test_cli_orders_request_no_stac(invoke):

result = invoke([
'request',
'PSOrthoTile',
'analytic',
'--item-type=PSOrthoTile',
'--bundle=analytic',
'--name=test',
'--id=4500474_2133707_2021-05-20_2419',
'4500474_2133707_2021-05-20_2419',
'--no-stac'
])

Expand Down