Skip to content

Commit e703ad3

Browse files
jreiberkylejreiberkyle
authored
Merge pull request #805 from planetlabs/requests-args-736
update planet orders request arguments
2 parents 8d67d23 + 415bd33 commit e703ad3

File tree

3 files changed

+85
-82
lines changed

3 files changed

+85
-82
lines changed

‎docs/cli/cli-orders.md

Lines changed: 28 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -107,19 +107,19 @@ If you don't have access to PlanetScope data then replace PSScene with SkySatCol
107107
Then make the following call:
108108

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

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

115115
```json
116-
{"name": "My First Order", "products": [{"item_ids": ["20220605_124027_64_242b"], "item_type": "PSScene", "product_bundle": "analytic_sr_udm2"}]}
116+
{"name": "My First Order", "products": [{"item_ids": ["20220605_124027_64_242b"], "item_type": "PSScene", "product_bundle": "analytic_sr_udm2"}], "metadata": {"stac": {}}}
117117
```
118118

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

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

125125
```json
@@ -133,7 +133,10 @@ planet orders request PSScene analytic_sr_udm2 --name 'My First Order' --id 2022
133133
"item_type": "PSScene",
134134
"product_bundle": "analytic_sr_udm2"
135135
}
136-
]
136+
],
137+
"metadata": {
138+
"stac": {}
139+
}
137140
}
138141
```
139142

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

145148
```console
146-
planet orders request PSScene analytic_sr_udm2 --name "My First Order" --id 20220605_124027_64_242b \
149+
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name "My First Order" 20220605_124027_64_242b \
147150
> request-1.json
148151
```
149152

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

202205
```console
203-
planet orders request PSScene analytic_sr_udm2 --name 'Two Item Order' \
204-
--id 20220605_124027_64_242b,20220605_124025_34_242b | planet orders create -
206+
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Two Item Order' \
207+
20220605_124027_64_242b,20220605_124025_34_242b | planet orders create -
205208
```
206209

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

359362
```console
360-
planet orders request PSScene analytic_sr_udm2 --clip geometry.geojson --name clipped-geom \
361-
--id 20220605_124027_64_242b | planet orders create -
363+
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --clip geometry.geojson --name clipped-geom \
364+
20220605_124027_64_242b | planet orders create -
362365
```
363366

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

408411
```console
409-
planet orders request PSScene analytic_sr_udm2 --name 'Two Scenes' \
410-
--id 20220605_124027_64_242b,20220605_124025_34_242b | planet orders create -
412+
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Two Scenes' \
413+
20220605_124027_64_242b,20220605_124025_34_242b | planet orders create -
411414
```
412415

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

428431
```console
429-
planet orders request PSScene analytic_sr_udm2 --name 'Two Scenes Composited' \
430-
--id 20220605_124027_64_242b,20220605_124025_34_242b --no-stac --tools tools-composite.json | planet orders create -
432+
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Two Scenes Composited' \
433+
20220605_124027_64_242b,20220605_124025_34_242b --no-stac --tools tools-composite.json | planet orders create -
431434
```
432435

433436
Note that we add the `--no-stac` option as [STAC Metadata](#stac-metadata) is not yet supported by the composite
@@ -452,8 +455,8 @@ as COG in the file format tool.
452455
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):
453456

454457
```console
455-
planet orders request PSScene analytic_sr_udm2 --name 'COG Order' \
456-
--id 20220605_124027_64_242b,20220605_124025_34_242b --tools tools-cog.json
458+
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'COG Order' \
459+
20220605_124027_64_242b,20220605_124025_34_242b --tools tools-cog.json
457460
```
458461

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

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

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

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

519522
### Harmonize
@@ -533,7 +536,7 @@ The harmonize tool allows you to compare data to different generations of satell
533536
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`.
534537

535538
```console
536-
planet orders request psscene analytic_sr_udm2 --name 'Harmonized data' --id 20200925_161029_69_2223 --tools tools-harmonize.json
539+
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Harmonized data' 20200925_161029_69_2223 --tools tools-harmonize.json
537540
```
538541

539542
## More options
@@ -668,9 +671,9 @@ image that was published:
668671

669672

670673
```console
671-
planet orders request SkySatCollect analytic --name 'SkySat Latest' \
672-
--id `planet data filter | planet data search SkySatCollect --sort 'acquired desc' --limit 1 - | jq -r .id` \
673-
| planet orders create -
674+
planet orders request --item-type SkySatCollect --bundle analytic --name 'SkySat Latest' \
675+
`planet data filter | planet data search SkySatCollect --sort 'acquired desc' --limit 1 - | jq -r .id` \
676+
| planet orders create -
674677
```
675678

676679
Or get the 5 latest cloud free images in an area and create an order that clips to that area, using
@@ -679,8 +682,8 @@ Or get the 5 latest cloud free images in an area and create an order that clips
679682
```console
680683
ids=`planet data filter --geom geometry.geojson --range clear_percent gt 90 | planet data \
681684
search PSScene --limit 5 - | jq -r .id | tr '\n' , | sed 's/.$//'`
682-
planet orders request PSScene analytic_sr_udm2 --name 'Clipped Scenes' \
683-
--id $ids --clip geometry.geojson | planet orders create -
685+
planet orders request --item-type PSScene --bundle analytic_sr_udm2 --name 'Clipped Scenes' \
686+
$ids --clip geometry.geojson | planet orders create -
684687
```
685688

686689
This one uses some advanced unix capabilities like `sed` and `tr`, along with unix variables, so more

‎planet/cli/orders.py

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -225,22 +225,21 @@ async def create(ctx, request: str, pretty):
225225
@click.pass_context
226226
@translate_exceptions
227227
@coro
228-
@click.argument('item_type',
229-
metavar='ITEM_TYPE',
230-
type=click.Choice(planet.specs.get_item_types(),
231-
case_sensitive=False))
232-
@click.argument('bundle',
233-
metavar='BUNDLE',
234-
type=click.Choice(planet.specs.get_product_bundles(),
235-
case_sensitive=False))
228+
@click.argument('ids', metavar='IDS', type=types.CommaSeparatedString())
229+
@click.option('--item-type',
230+
required=True,
231+
help='Item type for requested item ids.',
232+
type=click.Choice(planet.specs.get_item_types(),
233+
case_sensitive=False))
234+
@click.option('--bundle',
235+
required=True,
236+
help='Asset type for the item.',
237+
type=click.Choice(planet.specs.get_product_bundles(),
238+
case_sensitive=False))
236239
@click.option('--name',
237240
required=True,
238241
help='Order name. Does not need to be unique.',
239242
type=click.STRING)
240-
@click.option('--id',
241-
help='One or more comma-separated item IDs.',
242-
type=types.CommaSeparatedString(),
243-
required=True)
244243
@click.option('--clip',
245244
type=types.JSON(),
246245
help="""Clip feature GeoJSON. Can be a json string, filename,
@@ -270,7 +269,7 @@ async def request(ctx,
270269
item_type,
271270
bundle,
272271
name,
273-
id,
272+
ids,
274273
clip,
275274
tools,
276275
email,
@@ -280,11 +279,13 @@ async def request(ctx,
280279
"""Generate an order request.
281280
282281
This command provides support for building an order description used
283-
in creating an order. It outputs the order request, optionally pretty-
284-
printed.
282+
in creating an order. It outputs the order request, optionally
283+
pretty-printed.
284+
285+
IDs is one or more comma-separated item IDs.
285286
"""
286287
try:
287-
product = planet.order_request.product(id, bundle, item_type)
288+
product = planet.order_request.product(ids, bundle, item_type)
288289
except planet.specs.SpecificationException as e:
289290
raise click.BadParameter(e)
290291

‎tests/integration/test_orders_cli.py

Lines changed: 40 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -461,10 +461,10 @@ def test_cli_orders_request_basic_success(expected_ids,
461461
stac_json):
462462
result = invoke([
463463
'request',
464-
'PSOrthoTile',
465-
'analytic',
464+
'--item-type=PSOrthoTile',
465+
'--bundle=analytic',
466466
'--name=test',
467-
f'--id={id_string}',
467+
id_string,
468468
])
469469
assert not result.exception
470470

@@ -485,45 +485,44 @@ def test_cli_orders_request_basic_success(expected_ids,
485485
def test_cli_orders_request_item_type_invalid(invoke):
486486
result = invoke([
487487
'request',
488-
'invalid'
489-
'analytic',
488+
'--item-type=invalid'
489+
'--bundle=analytic',
490490
'--name=test',
491-
'--id=4500474_2133707_2021-05-20_2419',
491+
'4500474_2133707_2021-05-20_2419',
492492
])
493493
assert result.exit_code == 2
494-
error_msg = "Usage: main orders request [OPTIONS] ITEM_TYPE BUNDLE"
495-
assert error_msg in result.output
496494

497495

498496
def test_cli_orders_request_product_bundle_invalid(invoke):
499497
result = invoke([
500498
'request',
501-
'PSScene'
502-
'invalid',
499+
'--item-type=PSScene'
500+
'--bundle=invalid',
503501
'--name=test',
504-
'--id=4500474_2133707_2021-05-20_2419',
502+
'4500474_2133707_2021-05-20_2419',
505503
])
506504
assert result.exit_code == 2
507-
error_msg = "Usage: main orders request [OPTIONS] ITEM_TYPE BUNDLE"
508-
assert error_msg in result.output
509505

510506

511507
def test_cli_orders_request_product_bundle_incompatible(invoke):
512508
result = invoke([
513509
'request',
514-
'PSScene',
515-
'analytic',
510+
'--item-type=PSScene',
511+
'--bundle=analytic',
516512
'--name=test',
517-
'--id=4500474_2133707_2021-05-20_2419',
513+
'4500474_2133707_2021-05-20_2419',
518514
])
519515
assert result.exit_code == 2
520-
error_msg = "Usage: main orders request [OPTIONS] ITEM_TYPE BUNDLE"
521-
assert error_msg in result.output
522516

523517

524518
def test_cli_orders_request_id_empty(invoke):
525-
result = invoke(
526-
['request', 'PSOrthoTile', 'analytic', '--name=test', '--id='])
519+
result = invoke([
520+
'request',
521+
'--item-type=PSOrthoTile',
522+
'--bundle=analytic',
523+
'--name=test',
524+
''
525+
])
527526
assert result.exit_code == 2
528527
assert 'Entry cannot be an empty string.' in result.output
529528

@@ -541,10 +540,10 @@ def test_cli_orders_request_clip_success(geom_fixture,
541540

542541
result = invoke([
543542
'request',
544-
'PSOrthoTile',
545-
'analytic',
543+
'--item-type=PSOrthoTile',
544+
'--bundle=analytic',
546545
'--name=test',
547-
'--id=4500474_2133707_2021-05-20_2419',
546+
'4500474_2133707_2021-05-20_2419',
548547
f'--clip={json.dumps(geom)}',
549548
])
550549
assert result.exit_code == 0
@@ -571,10 +570,10 @@ def test_cli_orders_request_clip_success(geom_fixture,
571570
def test_cli_orders_request_clip_invalid_geometry(invoke, point_geom_geojson):
572571
result = invoke([
573572
'request',
574-
'PSOrthoTile',
575-
'analytic',
573+
'--item-type=PSOrthoTile',
574+
'--bundle=analytic',
576575
'--name=test',
577-
'--id=4500474_2133707_2021-05-20_2419',
576+
'4500474_2133707_2021-05-20_2419',
578577
f'--clip={json.dumps(point_geom_geojson)}'
579578
])
580579
assert result.exit_code == 2
@@ -588,10 +587,10 @@ def test_cli_orders_request_both_clip_and_tools(invoke, geom_geojson):
588587
# option values are valid json
589588
result = invoke([
590589
'request',
591-
'PSOrthoTile',
592-
'analytic',
590+
'--item-type=PSOrthoTile',
591+
'--bundle=analytic',
593592
'--name=test',
594-
'--id=4500474_2133707_2021-05-20_2419',
593+
'4500474_2133707_2021-05-20_2419',
595594
f'--clip={json.dumps(geom_geojson)}',
596595
f'--tools={json.dumps(geom_geojson)}'
597596
])
@@ -613,10 +612,10 @@ def test_cli_orders_request_cloudconfig(invoke, stac_json):
613612

614613
result = invoke([
615614
'request',
616-
'PSOrthoTile',
617-
'analytic',
615+
'--item-type=PSOrthoTile',
616+
'--bundle=analytic',
618617
'--name=test',
619-
'--id=4500474_2133707_2021-05-20_2419',
618+
'4500474_2133707_2021-05-20_2419',
620619
f'--cloudconfig={json.dumps(config_json)}',
621620
])
622621
assert result.exit_code == 0
@@ -640,10 +639,10 @@ def test_cli_orders_request_cloudconfig(invoke, stac_json):
640639
def test_cli_orders_request_email(invoke, stac_json):
641640
result = invoke([
642641
'request',
643-
'PSOrthoTile',
644-
'analytic',
642+
'--item-type=PSOrthoTile',
643+
'--bundle=analytic',
645644
'--name=test',
646-
'--id=4500474_2133707_2021-05-20_2419',
645+
'4500474_2133707_2021-05-20_2419',
647646
'--email'
648647
])
649648
assert result.exit_code == 0
@@ -671,10 +670,10 @@ def test_cli_orders_request_tools(invoke, geom_geojson, stac_json):
671670

672671
result = invoke([
673672
'request',
674-
'PSOrthoTile',
675-
'analytic',
673+
'--item-type=PSOrthoTile',
674+
'--bundle=analytic',
676675
'--name=test',
677-
'--id=4500474_2133707_2021-05-20_2419',
676+
'4500474_2133707_2021-05-20_2419',
678677
f'--tools={json.dumps(tools_json)}'
679678
])
680679

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

700699
result = invoke([
701700
'request',
702-
'PSOrthoTile',
703-
'analytic',
701+
'--item-type=PSOrthoTile',
702+
'--bundle=analytic',
704703
'--name=test',
705-
'--id=4500474_2133707_2021-05-20_2419',
704+
'4500474_2133707_2021-05-20_2419',
706705
'--no-stac'
707706
])
708707

0 commit comments

Comments
 (0)