Skip to content

Update subscriptions clip tool docstrings #1161

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 4 commits into from
Jun 30, 2025
Merged

Update subscriptions clip tool docstrings #1161

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
70d81c1
update subscriptions clip tool docstrings
asonnenschein Jun 27, 2025
833bbbb
update guide
asonnenschein Jun 30, 2025
ad76646
Update docs/python/sdk-guide.md
asonnenschein Jun 30, 2025
56d7498
shuffle order of ops in user guide
asonnenschein Jun 30, 2025
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
7 changes: 5 additions & 2 deletions docs/python/sdk-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,8 @@ You will need your ACCESS_KEY_ID, SECRET_ACCESS_KEY, bucket and region name.
To subscribe to scenes that match a filter, use the `subscription_request` module to build a request, and
pass it to the `subscriptions.create_subscription()` method of the client.

By default, a request to create a subscription will not clip matching imagery which intersects the source geometry. To clip to the subscription source geometry, set `planet.subscription_request.build_request()` keyword argument `clip_to_source = True` as in the example below. To clip to a custom geometry, set `planet.subscription_request.build_request()` keyword argument `clip_to_source = False` (or omit it entirely to fall back on the default value), and instead configure the custom clip AOI with `planet.subscription_request.clip_tool()`.

Warning: the following code will create a subscription, consuming quota based on your plan.

```python
Expand All @@ -256,11 +258,12 @@ source = catalog_source(
time_range_type="acquired",
)

request = build_request("Standard PSScene Ortho Analytic", source=source, delivery={})

# define a delivery method. In this example, we're using AWS S3.
delivery = amazon_s3(ACCESS_KEY_ID, SECRET_ACCESS_KEY, "test", "us-east-1")

# build the request payload
request = build_request("Standard PSScene Ortho Analytic", source=source, delivery=delivery, clip_to_source=True)

# finally, create the subscription
subscription = pl.subscriptions.create_subscription(request)
```
Expand Down
24 changes: 11 additions & 13 deletions planet/subscription_request.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,15 +71,11 @@ def build_request(name: str,
hosting: A hosting destination e.g. Sentinel Hub.
collection_id: A Sentinel Hub collection ID.
create_configuration: Automatically create a layer configuration for your collection.
clip_to_source: whether to clip to the source geometry or not
(the default). If True a clip configuration will be added to
the list of requested tools unless an existing clip tool
exists. NOTE: Not all data layers support clipping, please
consult the Product reference before using this option.
NOTE: the next version of the Subscription API will remove
the clip tool option and always clip to the source geometry.
Thus this is a preview of the next API version's default
behavior.
clip_to_source: Whether or not to clip to the source geometry (defaults to False). If
True, a clip configuration that specifies the subscription source geometry as clip
AOI will be added to the list of requested tools. If True and 'clip_tool()' is
also specified, an exception will be raised. If False, no clip configuration
will be added to the list of requested tools unless 'clip_tool()' is specified.

Returns:
dict: a representation of a Subscriptions API request for
Expand Down Expand Up @@ -133,10 +129,7 @@ def build_request(name: str,

# If clip_to_source is True a clip configuration will be added
# to the list of requested tools unless an existing clip tool
# exists. In that case an exception is raised. NOTE: the next
# version of the Subscription API will remove the clip tool
# option and always clip to the source geometry. Thus this is a
# preview of the next API version's default behavior.
# exists. In that case an exception is raised.
if clip_to_source:
if any(tool.get('type', None) == 'clip' for tool in tool_list):
raise ClientError(
Expand Down Expand Up @@ -656,6 +649,10 @@ def clip_tool(aoi: Mapping) -> dict:
the clip aoi is so large that full scenes may be delivered without any
clipping, those files will not have “_clip” appended to their file name.

NOTE: To clip to the source geometry, set the 'clip_to_source' parameter
of 'planet.subscription_request.build_request()' to True instead of using
this tool.

Parameters:
aoi: GeoJSON polygon or multipolygon defining the clip area, with up to
500 vertices. The minimum geographic area of any polygon or
Expand All @@ -665,6 +662,7 @@ def clip_tool(aoi: Mapping) -> dict:
planet.exceptions.ClientError: If aoi is not a valid polygon or
multipolygon.
"""

valid_types = ['Polygon', 'MultiPolygon', 'ref']

geom = geojson.as_geom_or_ref(dict(aoi))
Expand Down