From 70d81c177dbfd3d5fd9f0f3221e23309e4bc0809 Mon Sep 17 00:00:00 2001 From: asonnenschein Date: Fri, 27 Jun 2025 13:28:01 -0400 Subject: [PATCH 1/4] update subscriptions clip tool docstrings --- planet/subscription_request.py | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/planet/subscription_request.py b/planet/subscription_request.py index 2380c3c85..4aa4b5ead 100644 --- a/planet/subscription_request.py +++ b/planet/subscription_request.py @@ -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 @@ -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( @@ -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 @@ -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)) From 833bbbba5cbfe5ab4b2ea2e0c29a4e13b06582d6 Mon Sep 17 00:00:00 2001 From: asonnenschein Date: Mon, 30 Jun 2025 10:44:58 -0400 Subject: [PATCH 2/4] update guide --- docs/python/sdk-guide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/python/sdk-guide.md b/docs/python/sdk-guide.md index 70ea5bbc2..3b4350c6a 100644 --- a/docs/python/sdk-guide.md +++ b/docs/python/sdk-guide.md @@ -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 to the subscription source geometry. To clip to 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 @@ -256,7 +258,7 @@ source = catalog_source( time_range_type="acquired", ) -request = build_request("Standard PSScene Ortho Analytic", source=source, delivery={}) +request = build_request("Standard PSScene Ortho Analytic", source=source, delivery={}, clip_to_source=True) # 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") From ad766463d452701f05240e200221a02df7a02168 Mon Sep 17 00:00:00 2001 From: Adrian Sonnenschein Date: Mon, 30 Jun 2025 11:01:08 -0400 Subject: [PATCH 3/4] Update docs/python/sdk-guide.md Co-authored-by: Adam Weiner --- docs/python/sdk-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/python/sdk-guide.md b/docs/python/sdk-guide.md index 3b4350c6a..f60e8aa59 100644 --- a/docs/python/sdk-guide.md +++ b/docs/python/sdk-guide.md @@ -231,7 +231,7 @@ 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 to the subscription source geometry. To clip to 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()`. +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. From 56d7498c36d7c498021cdcd897a9df98edfd4031 Mon Sep 17 00:00:00 2001 From: asonnenschein Date: Mon, 30 Jun 2025 11:04:57 -0400 Subject: [PATCH 4/4] shuffle order of ops in user guide --- docs/python/sdk-guide.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/python/sdk-guide.md b/docs/python/sdk-guide.md index f60e8aa59..5dcd71c3d 100644 --- a/docs/python/sdk-guide.md +++ b/docs/python/sdk-guide.md @@ -258,11 +258,12 @@ source = catalog_source( time_range_type="acquired", ) -request = build_request("Standard PSScene Ortho Analytic", source=source, delivery={}, clip_to_source=True) - # 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) ```