Repository: planetlabs/planet-client-python

Issue:
Recommend clip-to-source in subscription docs
For example, this section can be mostly eliminated https://planet-sdk-for-python-v2.readthedocs.io/en/latest/cli/cli-subscriptions/#clipping.

Comments:

Patch:
diff --git a/CHANGES.txt b/CHANGES.txt
index a78e118..fc85a88 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,5 +1,7 @@
 2.1.0 (TBD)
 
+- Support for publishing stages and time range types has been added to the
+  subscriptions CLI (#992).
 - The --cloudconfig option of the request command of the orders CLI has been
   superseded by a new --delivery option, with --cloudconfig left as an alias.
   New --archive-type, --archive-filename, and --single-archive options to
diff --git a/docs/cli/cli-orders.md b/docs/cli/cli-orders.md
index ff0dd76..48d9d27 100644
--- a/docs/cli/cli-orders.md
+++ b/docs/cli/cli-orders.md
@@ -149,6 +149,33 @@ planet orders request \
 }
 ```
 
+#### Zip archives of bundles and orders
+
+You can request that all files of a bundle be zipped together by using the `--archive-type` option. The only type of archive currently available is "zip".
+
+```sh
+planet orders request \
+    --item-type PSScene \
+    --bundle analytic_sr_udm2 \
+    --name 'My First Zipped Order' \
+    --archive-type zip \
+    20220605_124027_64_242b
+```
+
+You can request that all files of the entire order be zipped together by using the `--single-archive` option.
+
+```sh
+planet orders request \
+    --item-type PSScene \
+    --bundle analytic_sr_udm2 \
+    --name 'My First Zipped Order' \
+    --archive-type zip \
+    --single-archive \
+    20220605_124027_64_242b,20220605_124025_34_242b
+```
+
+*New in version 2.1*
+
 ### Save an Order Request
 
 The above command just prints out the necessary JSON to create an order. To actually use it you can
@@ -613,13 +640,13 @@ Orders with Google Earth Engine delivery will force the STAC flag to false.
 ### Cloud Delivery
 
 Another option is to delivery your orders directly to a cloud bucket, like AWS S3 or Google Cloud Storage.
-The file given with the `--cloudconfig` option should contain JSON that follows
+The file given with the `--delivery` option should contain JSON that follows
 the options and format given in
 [Delivery to Cloud Storage](https://developers.planet.com/docs/orders/delivery/#delivery-to-cloud-storage).
 
 An example would be:
 
-Example: `cloudconfig.json`
+Example: `delivery.json`
 
 ```json
 {
@@ -633,6 +660,12 @@ Example: `cloudconfig.json`
 }
 ```
 
+*New in 2.1*
+
+!!! note
+
+    `--cloudconfig` was the name of this option in version 2.0 and can continue to be used as an alias for `--delivery`.
+
 ### Using Orders output as input
 
 One useful thing to note is that the order JSON that reports status and location is a valid Orders API request.
diff --git a/docs/cli/cli-subscriptions.md b/docs/cli/cli-subscriptions.md
index 1e48fb1..006aa5f 100644
--- a/docs/cli/cli-subscriptions.md
+++ b/docs/cli/cli-subscriptions.md
@@ -157,21 +157,33 @@ planet subscriptions get cb817760-1f07-4ee7-bba6-bcac5346343f
 To see what items have been delivered to your cloud bucket you can use the `results` command:
 
 ```sh
-planet subscriptions results cb817760-1f07-4ee7-bba6-bcac5346343f
+planet subscriptions results SUBSCRIPTION_ID
 ```
 
+`SUBSCRIPTION_ID` above is a placeholder for a unique subscription identifier, which will be a UUID like `cb817760-1f07-4ee7-bba6-bcac5346343f`.
+
 By default this displays the first 100 results. As with other commands, you can use the `--limit` param to 
 set a higher limit, or set it to 0 to see all results (this can be quite large with subscriptions results).
 
 You can also filter by status:
 
 ```sh
-planet subscriptions results --status processing
+planet subscriptions results SUBSCRIPTION_ID --status processing
 ```
 
 The available statuses are `created`, `queued`, `processing`, `failed`, and `success`. Note it’s quite useful
 to use `jq` to help filter out results as well.  
 
+#### Results as comma-seperated values (CSV)
+
+Planetary Variable subscribers can benefit from retrieving results as a CSV. The results contain variable statistics and can serve as data for time series analysis and visualization.
+
+```sh
+planet subscriptions results SUBSCRIPTION_ID --csv
+```
+
+*New in version 2.1*
+
 ### Update Subscription
 
 You can update a subscription that is running, for example to change the 'tools' it’s using or to alter
@@ -306,6 +318,28 @@ planet data filter --range clear_percent gt 90 \
 
 Do not bother with geometry or date filters, as they will be ignored in favor of the `--start-time` and `--geometry` values that are required.
 
+#### Publishing stages and time range types
+
+By using the `--time-range-type` you can choose to temporally filter by
+acquisition or publication time. The `--publishing-stage` option allows you to
+receive the earliest preview imagery or wait until finalized imagery is
+available. See [Catalog Source
+Types:Parameters](https://developers.planet.com/docs/subscriptions/source/#parameters)
+for more details.
+
+```sh
+planet subscriptions request-catalog \
+    --item-types PSScene \
+    --asset-types ortho_analytic_8b \
+    --geometry geometry.geojson \
+    --start-time 2022-08-24T00:00:00-07:00 \
+    --time-range-type acquired \
+    --publishing-stage finalized \
+    --filter filter.json
+```
+
+*New in version 2.1*
+
 #### Saving the output
 
 You’ll likely want to save the output of your `request-catalog` call to disk, so that you can more easily use it in constructing the complete subscription
@@ -321,6 +355,25 @@ planet subscriptions request-catalog \
     --filter filter.json > request-catalog.json
 ```
 
+### Planetary Variable Request
+
+Subscribing to Planetary Variables is much like subscribing to imagery from
+Planet's catalog. The `planet subscriptions request-pv` command can construct the source
+part of a Planetary Variable request like `request-catalog` does for cataloged
+imagery. Planetary Variable subscriptions come in 4 types and are further
+subdivided within these types by an identifier. See [Subscribing to Planetary
+Variables](https://developers.planet.com/docs/subscriptions/pvs-subs/#planetary-variables-types-and-ids)
+for details. To constrain data delivery by space and time, you will use the
+`--geometry`, `start-time`, and `end-time` options described above.
+
+```sh
+planet subscriptions request-pv \
+    --var-type biomass_proxy \
+    --var-id BIOMASS-PROXY_V3.0_10 \
+    --geometry geometry.geojson \
+    --start-time 2022-08-24T00:00:00-07:00 > request-pv.json
+```
+
 ### Subscription Tools
 
 Now we’ll dive into some of the tools options for subscriptions. These are quite similar to the tools for 
@@ -332,51 +385,18 @@ for Orders, future of the versions of the CLI will likely add `tools` convenienc
 
 The most used tool is the `clip` operation, which lets you pass a geometry to the
 Subscriptions API and it creates new images that only have pixels within the geometry you
-gave it. We’ll use the same geometry from [above](#geometry), as it is quite
-typical to use the same subscription geometry as the clip geometry, so you don't get
-any pixels outside of your area of interest (99.9% of all subscriptions use the clip
-tool, so it’s strongly recommended to also use clip). The proper 'clip' tool for it
-would be:
+gave it. 99% of the time you will want to clip to the subscription geometry. The easiest way to do this is to use the `--clip-to-source` option added to the `subscriptions request` command in version 2.1.
 
-```json
-[
-    {
-        "type": "clip",
-        "parameters": {
-            "aoi": {
-                "type": "Polygon",
-                "coordinates": [
-                    [
-                        [
-                            -163.828125,
-                            -44.59046718130883
-                        ],
-                        [
-                            181.7578125,
-                            -44.59046718130883
-                        ],
-                        [
-                            181.7578125,
-                            78.42019327591201
-                        ],
-                        [
-                            -163.828125,
-                            78.42019327591201
-                        ],
-                        [
-                            -163.828125,
-                            -44.59046718130883
-                        ]
-                    ]
-                ]
-            }
-        }
-    }
-]
+```sh
+planet subscriptions request \
+    --name 'Clipped Subscription' \
+    --source request-catalog.json \
+    --delivery cloud-delivery.json \
+    --clip-to-source
 ```
 
-You can save this tools as `tools.json` to include in the `subscriptions request` 
-command.
+*New in version 2.1*
+
 
 #### Additional Tools
 
diff --git a/planet/cli/subscriptions.py b/planet/cli/subscriptions.py
index eebc1a8..f3f1b37 100644
--- a/planet/cli/subscriptions.py
+++ b/planet/cli/subscriptions.py
@@ -301,6 +301,16 @@ def request(name,
     '--filter',
     type=types.JSON(),
     help='Search filter.  Can be a string, filename, or - for stdin.')
+@click.option(
+    '--publishing-stage',
+    'publishing_stages',
+    type=click.Choice(["preview", "standard", "finalized"]),
+    multiple=True,
+    help=("Subscribe to results at a particular publishing stage. Multiple "
+          "instances of this option are allowed."))
+@click.option('--time-range-type',
+              type=click.Choice(["acquired", "published"]),
+              help="Subscribe by acquisition time or time of publication.")
 @pretty
 def request_catalog(item_types,
                     asset_types,
@@ -309,15 +319,20 @@ def request_catalog(item_types,
                     end_time,
                     rrule,
                     filter,
+                    publishing_stages,
+                    time_range_type,
                     pretty):
     """Generate a subscriptions request catalog source description."""
-    res = subscription_request.catalog_source(item_types,
-                                              asset_types,
-                                              geometry,
-                                              start_time,
-                                              end_time=end_time,
-                                              rrule=rrule,
-                                              filter=filter)
+    res = subscription_request.catalog_source(
+        item_types,
+        asset_types,
+        geometry,
+        start_time,
+        end_time=end_time,
+        rrule=rrule,
+        filter=filter,
+        publishing_stages=publishing_stages,
+        time_range_type=time_range_type)
     echo_json(res, pretty)
 
 


Test patch:
diff --git a/tests/integration/test_subscriptions_cli.py b/tests/integration/test_subscriptions_cli.py
index a1b3cea..1e40eb9 100644
--- a/tests/integration/test_subscriptions_cli.py
+++ b/tests/integration/test_subscriptions_cli.py
@@ -12,6 +12,7 @@ There are 6 subscriptions commands:
 TODO: tests for 3 options of the planet-subscriptions-results command.
 
 """
+import itertools
 import json
 
 from click.testing import CliRunner
@@ -356,3 +357,46 @@ def test_request_pv_success(invoke, geom_geojson):
     source = json.loads(result.output)
     assert source["type"] == "biomass_proxy"
     assert source["parameters"]["id"] == "BIOMASS-PROXY_V3.0_10"
+
+
+@pytest.mark.parametrize(
+    # Test all the combinations of the three options plus some with dupes.
+    "publishing_stages",
+    list(
+        itertools.chain.from_iterable(
+            itertools.combinations(["preview", "standard", "finalized"], i)
+            for i in range(1, 4))) + [("preview", "preview"),
+                                      ("preview", "finalized", "preview")])
+def test_catalog_source_publishing_stages(invoke,
+                                          geom_geojson,
+                                          publishing_stages):
+    """Catalog source publishing stages are configured."""
+    result = invoke([
+        'request-catalog',
+        '--item-types=PSScene',
+        '--asset-types=ortho_analytic_4b',
+        f"--geometry={json.dumps(geom_geojson)}",
+        '--start-time=2021-03-01T00:00:00',
+    ] + [f'--publishing-stage={stage}' for stage in publishing_stages])
+
+    assert result.exit_code == 0  # success.
+    req = json.loads(result.output)
+    assert req['parameters']['publishing_stages'] == list(
+        set(publishing_stages))
+
+
+@pytest.mark.parametrize("time_range_type", ["acquired", "published"])
+def test_catalog_source_time_range_type(invoke, geom_geojson, time_range_type):
+    """Catalog source time range type is configured."""
+    result = invoke([
+        'request-catalog',
+        '--item-types=PSScene',
+        '--asset-types=ortho_analytic_4b',
+        f"--geometry={json.dumps(geom_geojson)}",
+        '--start-time=2021-03-01T00:00:00',
+        f'--time-range-type={time_range_type}',
+    ])
+
+    assert result.exit_code == 0  # success.
+    req = json.loads(result.output)
+    assert req['parameters']['time_range_type'] == time_range_type