Update subscriptions clip tool docstrings (#1161)

* update subscriptions clip tool docstrings

* update guide

* Update docs/python/sdk-guide.md

Co-authored-by: Adam Weiner <[email protected]>

* shuffle order of ops in user guide

---------

Co-authored-by: Adam Weiner <[email protected]>

Author: asonnenschein

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 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
@@ -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)
 ```

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))