Skip to content

Commit 4055dbb

Browse files
sgilliessgillies
authored
Merge pull request #984 from planetlabs/rel-2.1b1
Release 2.1b1
2 parents 53b9478 + 3a21689 commit 4055dbb

File tree

6 files changed

+192
-69
lines changed

6 files changed

+192
-69
lines changed

‎CHANGES.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
2.1.0 (TBD)
22

3+
2.1b1 (2023-07-11)
4+
35
Added:
6+
- The request command of the subscriptions CLI has a new --clip-to-source
7+
option (#988).
8+
- A new request-pv command has been added to the subscriptions CLi (#988).
49
- Support for catalog source publishing stages (#977) and time range types
510
(#978) have been added to subscription_request.catalog_source.
611
- Add the option to get Planetary Variable subscription results as a CSV file

‎planet/__version__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
__version__ = '2.1.0dev'
1+
__version__ = '2.1dev'

‎planet/cli/subscriptions.py

Lines changed: 67 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -238,14 +238,32 @@ async def list_subscription_results_cmd(ctx,
238238
'--tools',
239239
type=types.JSON(),
240240
help='Toolchain JSON. Can be a string, filename, or - for stdin.')
241+
@click.option(
242+
'--clip-to-source',
243+
is_flag=True,
244+
default=False,
245+
help="Clip to the source geometry without specifying a clip tool.")
241246
@pretty
242-
def request(name, source, delivery, notifications, tools, pretty):
243-
"""Generate a subscriptions request."""
247+
def request(name,
248+
source,
249+
delivery,
250+
notifications,
251+
tools,
252+
clip_to_source,
253+
pretty):
254+
"""Generate a subscriptions request.
255+
256+
Note: the next version of the Subscription API will remove the clip
257+
tool option and always clip to the source geometry. Thus the
258+
--clip-to-source option is a preview of the next API version's
259+
default behavior.
260+
"""
244261
res = subscription_request.build_request(name,
245262
source,
246263
delivery,
247264
notifications=notifications,
248-
tools=tools)
265+
tools=tools,
266+
clip_to_source=clip_to_source)
249267
echo_json(res, pretty)
250268

251269

@@ -298,3 +316,49 @@ def request_catalog(item_types,
298316
rrule=rrule,
299317
filter=filter)
300318
echo_json(res, pretty)
319+
320+
321+
@subscriptions.command() # type: ignore
322+
@translate_exceptions
323+
@click.option(
324+
'--var-type',
325+
required=True,
326+
help='Planetary variable type.',
327+
type=click.Choice([
328+
"biomass_proxy",
329+
"land_surface_temperature",
330+
"soil_water_content",
331+
"vegetation_optical_depth"
332+
]),
333+
)
334+
@click.option('--var-id', required=True, help='Planetary variable id.')
335+
@click.option(
336+
'--geometry',
337+
required=True,
338+
type=types.JSON(),
339+
help="""Geometry of the area of interest of the subscription that will be
340+
used to determine matches. Can be a string, filename, or - for stdin.""")
341+
@click.option('--start-time',
342+
required=True,
343+
type=types.DateTime(),
344+
help='Date and time to begin subscription.')
345+
@click.option('--end-time',
346+
type=types.DateTime(),
347+
help='Date and time to end subscription.')
348+
@pretty
349+
def request_pv(var_type, var_id, geometry, start_time, end_time, pretty):
350+
"""Generate a Planetary Variable subscription source.
351+
352+
Planetary Variables come in 4 types and are further subdivided
353+
within these types. See [Subscribing to Planetary
354+
Variables](https://developers.planet.com/docs/subscriptions/pvs-subs/#planetary-variables-types-and-ids)
355+
for details.
356+
"""
357+
res = subscription_request.planetary_variable_source(
358+
var_type,
359+
var_id,
360+
geometry,
361+
start_time,
362+
end_time=end_time,
363+
)
364+
echo_json(res, pretty)

‎planet/subscription_request.py

Lines changed: 75 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -81,30 +81,32 @@ def build_request(name: str,
8181
constructed.
8282
8383
Examples:
84+
8485
```python
85-
>>> from datetime import datetime
86-
>>> from planet.subscription_request import (
87-
... build_request, catalog_source, amazon_s3)
88-
...
89-
... geom = {
90-
... "coordinates": [[[139.5648193359375,35.42374884923695],
91-
... [140.1031494140625,35.42374884923695],
92-
... [140.1031494140625,35.77102915686019],
93-
... [139.5648193359375,35.77102915686019],
94-
... [139.5648193359375,35.42374884923695]]],
95-
... "type": "Polygon"
96-
... }
97-
>>> source = catalog_source(
98-
... ["PSScene"], ["ortho_analytic_4b"], geom, datetime(2021,3,1))
99-
100-
>>> delivery = amazon_s3(
101-
... ACCESS_KEY_ID, SECRET_ACCESS_KEY, "test", "us-east-1")
102-
...
103-
>>> subscription_request = build_request(
104-
... 'test_subscription', source=source, delivery=delivery)
105-
...
106-
107-
```
86+
from datetime import datetime
87+
from planet.subscription_request import build_request, catalog_source, amazon_s3
88+
89+
geom = {
90+
"coordinates": [
91+
[
92+
[139.5648193359375, 35.42374884923695],
93+
[140.1031494140625, 35.42374884923695],
94+
[140.1031494140625, 35.77102915686019],
95+
[139.5648193359375, 35.77102915686019],
96+
[139.5648193359375, 35.42374884923695],
97+
]
98+
],
99+
"type": "Polygon",
100+
}
101+
102+
source = catalog_source(["PSScene"], ["ortho_analytic_4b"], geom, datetime(2021, 3, 1))
103+
104+
delivery = amazon_s3(ACCESS_KEY_ID, SECRET_ACCESS_KEY, "test", "us-east-1")
105+
106+
subscription_request = build_request(
107+
"test_subscription", source=source, delivery=delivery
108+
)
109+
```
108110
"""
109111
# Because source and delivery are Mappings we must make copies for
110112
# the function's return value. dict() shallow copies a Mapping
@@ -116,8 +118,8 @@ def build_request(name: str,
116118
if notifications:
117119
details['notifications'] = dict(notifications)
118120

119-
if tools:
120-
tool_list = [dict(tool) for tool in tools]
121+
if tools or clip_to_source:
122+
tool_list = [dict(tool) for tool in (tools or [])]
121123

122124
# If clip_to_source is True a clip configuration will be added
123125
# to the list of requested tools unless an existing clip tool
@@ -179,6 +181,7 @@ def catalog_source(
179181
Only monthly recurrences are supported at this time.
180182
publishing_stages: A sequence of one or more of the values
181183
"preview", "standard", or "finalized".
184+
time_range_type: "acquired" (new in 2.1.0) or "published".
182185
183186
Returns:
184187
dict: a representation of a subscription source.
@@ -188,28 +191,30 @@ def catalog_source(
188191
configured.
189192
190193
Examples:
191-
```pycon
192-
>>> source = catalog_source(
193-
... ["PSScene"],
194-
... ["ortho_analytic_4b"],
195-
... geometry={
196-
... "type": "Polygon",
197-
... "coordinates": [[[37.791595458984375, 14.84923123791421],
198-
... [37.90214538574219, 14.84923123791421],
199-
... [37.90214538574219, 14.945448293647944],
200-
... [37.791595458984375, 14.945448293647944],
201-
... [37.791595458984375, 14.84923123791421]]]
202-
... },
203-
... start_time=datetime(2021, 3, 1),
204-
... publishing_stages=["standard"],
205-
... time_range_type="acquired",
206-
... )
207-
>>> request = build_request(
208-
... "Standard PSScene Ortho Analytic",
209-
... source=source,
210-
... delivery={})
211-
```
212194
195+
```python
196+
source = catalog_source(
197+
["PSScene"],
198+
["ortho_analytic_4b"],
199+
geometry={
200+
"type": "Polygon",
201+
"coordinates": [
202+
[
203+
[37.791595458984375, 14.84923123791421],
204+
[37.90214538574219, 14.84923123791421],
205+
[37.90214538574219, 14.945448293647944],
206+
[37.791595458984375, 14.945448293647944],
207+
[37.791595458984375, 14.84923123791421],
208+
]
209+
],
210+
},
211+
start_time=datetime(2021, 3, 1),
212+
publishing_stages=["standard"],
213+
time_range_type="acquired",
214+
)
215+
216+
request = build_request("Standard PSScene Ortho Analytic", source=source, delivery={})
217+
```
213218
"""
214219
if len(item_types) > 1:
215220
raise ClientError(
@@ -297,24 +302,31 @@ def planetary_variable_source(
297302
configured.
298303
299304
Examples:
305+
300306
```python
301-
>>> source = planetary_variable_source(
302-
... "soil_water_content",
303-
... "SWC-AMSR2-C_V1.0_100",
304-
... geometry={
305-
... "type": "Polygon",
306-
... "coordinates": [[[37.791595458984375, 14.84923123791421],
307-
... [37.90214538574219, 14.84923123791421],
308-
... [37.90214538574219, 14.945448293647944],
309-
... [37.791595458984375, 14.945448293647944],
310-
... [37.791595458984375, 14.84923123791421]]]
311-
... },
312-
... start_time=datetime(2021, 3, 1)
313-
... )
314-
>>> request = build_request(
315-
... "Soil Water Content",
316-
... source=source,
317-
... delivery={})
307+
pv_source = planetary_variables_source(
308+
"soil_water_content",
309+
"SWC-AMSR2-C_V1.0_100",
310+
geometry={
311+
"type": "Polygon",
312+
"coordinates": [
313+
[
314+
[37.791595458984375, 14.84923123791421],
315+
[37.90214538574219, 14.84923123791421],
316+
[37.90214538574219, 14.945448293647944],
317+
[37.791595458984375, 14.945448293647944],
318+
[37.791595458984375, 14.84923123791421],
319+
]
320+
],
321+
},
322+
start_time=datetime(2021, 3, 1),
323+
)
324+
325+
request = build_request(
326+
"soil_water_subscription",
327+
source=pv_source,
328+
delivery={},
329+
)
318330
```
319331
"""
320332
# TODO: validation of variable types and ids.

‎tests/integration/test_subscriptions_api.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
"""Tests of the Planet Subscriptions API client."""
22

3+
import csv
34
from datetime import datetime
45
from itertools import zip_longest
56
import json
@@ -288,7 +289,6 @@ async def test_get_results_csv():
288289
async with Session() as session:
289290
client = SubscriptionsClient(session, base_url=TEST_URL)
290291
results = [res async for res in client.get_results_csv("42")]
291-
import csv
292292
rows = list(csv.reader(results))
293293
assert rows == [['id', 'status'], ['1234-abcd', 'SUCCESS']]
294294

‎tests/integration/test_subscriptions_cli.py

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -252,7 +252,7 @@ def test_subscriptions_results_success(invoke, options, expected_count):
252252

253253

254254
def test_request_base_success(invoke, geom_geojson):
255-
"""Request command succeeds"""
255+
"""Request command succeeds."""
256256
source = json.dumps({
257257
"type": "catalog",
258258
"parameters": {
@@ -285,6 +285,32 @@ def test_request_base_success(invoke, geom_geojson):
285285
assert result.exit_code == 0 # success.
286286

287287

288+
def test_request_base_clip_to_source(invoke, geom_geojson):
289+
"""Clip to source using command line option."""
290+
source = json.dumps({
291+
"type": "catalog",
292+
"parameters": {
293+
"geometry": geom_geojson,
294+
"start_time": "2021-03-01T00:00:00Z",
295+
"item_types": ["PSScene"],
296+
"asset_types": ["ortho_analytic_4b"]
297+
}
298+
})
299+
result = invoke([
300+
'request',
301+
'--name=test',
302+
f'--source={source}',
303+
'--delivery={"type": "fake"}',
304+
'--clip-to-source'
305+
])
306+
307+
assert result.exit_code == 0 # success.
308+
req = json.loads(result.output)
309+
tool = req["tools"][0]
310+
assert tool["type"] == "clip"
311+
assert tool["parameters"]["aoi"] == geom_geojson
312+
313+
288314
def test_request_catalog_success(invoke, geom_geojson):
289315
"""Request-catalog command succeeds"""
290316
source = {
@@ -314,3 +340,19 @@ def test_subscriptions_results_csv(invoke):
314340
result = invoke(['results', 'test', '--csv'])
315341
assert result.exit_code == 0 # success.
316342
assert result.output.splitlines() == ['id,status', '1234-abcd,SUCCESS']
343+
344+
345+
def test_request_pv_success(invoke, geom_geojson):
346+
"""Request-pv command succeeds"""
347+
result = invoke([
348+
'request-pv',
349+
'--var-type=biomass_proxy',
350+
'--var-id=BIOMASS-PROXY_V3.0_10',
351+
f"--geometry={json.dumps(geom_geojson)}",
352+
'--start-time=2021-03-01T00:00:00'
353+
])
354+
355+
assert result.exit_code == 0 # success.
356+
source = json.loads(result.output)
357+
assert source["type"] == "biomass_proxy"
358+
assert source["parameters"]["id"] == "BIOMASS-PROXY_V3.0_10"

0 commit comments

Comments
 (0)