Refactor planetary_variable_source() signature (#1170)

* remove source type param from pv source method

* docs

* update method names and signatrues

Author: asonnenschein

docs/cli/cli-subscriptions.md

@@ -450,22 +450,21 @@ 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://docs.planet.com/develop/apis/subscriptions/sources/#planetary-variable-and-analysis-ready-source-types)
-for details. To constrain data delivery by space and time, you will use the
+### Planetary Variable and Analysis-Ready Source Requests
+
+Subscribing to Planetary Variables and Analysis-Ready data is much like subscribing to imagery from
+Planet's catalog. The `planet subscriptions request-source` command can construct the source
+part of a Planetary Variable or Analysis-Ready source request like `request-catalog` does for cataloged
+imagery. See [Subscribing to Planetary
+Variables and Analysis Ready sources](https://docs.planet.com/develop/apis/subscriptions/sources/#planetary-variable-and-analysis-ready-source-types)
+for details about different product options. 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-id BIOMASS-PROXY_V3.0_10 \
+planet subscriptions request-source \
+    --source-id BIOMASS-PROXY_V3.0_10 \
     --geometry geometry.geojson \
-    --start-time 2022-08-24T00:00:00-07:00 > request-pv.json
+    --start-time 2022-08-24T00:00:00-07:00 > request-source.json
 ```
 
 ### Subscription Tools

docs/hooks/mkdocs_hooks.py

@@ -1,5 +1,6 @@
 from planet import __version__ as _pl_sdk_version
 
+
 def on_config(config):
     """
     This is for injecting the package version into mkdocs

planet/cli/subscriptions.py

@@ -535,15 +535,9 @@ def request_catalog(item_types,
 
 @subscriptions.command()  # type: ignore
 @translate_exceptions
-@click.option(
-    '--var-type',
-    required=False,
-    help='A Planetary Variable type. See documentation for all available types.'
-)
-@click.option(
-    '--var-id',
-    required=True,
-    help='A Planetary Variable ID. See documentation for all available IDs.')
+@click.option('--source-id',
+              required=True,
+              help='A source ID. See documentation for all available IDs.')
 @click.option(
     '--geometry',
     required=True,
@@ -559,17 +553,14 @@ def request_catalog(item_types,
               type=types.DateTime(),
               help='Date and time to end subscription.')
 @pretty
-def request_pv(var_type, var_id, geometry, start_time, end_time, pretty):
-    """Generate a Planetary Variable subscription source.
+def request_source(source_id, geometry, start_time, end_time, pretty):
+    """Generate a subscription source.
 
-    Planetary Variables come in 4 types and are further subdivided
-    within these types. See [Subscribing to Planetary Variables](https://docs.planet.com/develop/apis/subscriptions/sources/#planetary-variable-and-analysis-ready-source-types)
-    or the [OpenAPI spec](https://api.planet.com/subscriptions/v1/spec) for
-    more details.
+    See [Subscribing to Planetary Variables and Analysis Ready sources](https://docs.planet.com/develop/apis/subscriptions/sources/#planetary-variable-and-analysis-ready-source-types)
+    or the [OpenAPI spec](https://api.planet.com/subscriptions/v1/spec) to learn more about different product options.
     """
-    res = subscription_request.planetary_variable_source(
-        var_type,
-        var_id,
+    res = subscription_request.subscription_source(
+        source_id,
         geometry,
         start_time,
         end_time=end_time,

planet/subscription_request.py

@@ -272,30 +272,24 @@ def catalog_source(
     return {"parameters": parameters}
 
 
-def planetary_variable_source(
-    var_type: Optional[str],
-    var_id: str,
+def subscription_source(
+    source_id: str,
     geometry: Union[dict, str],
     start_time: datetime,
     end_time: Optional[datetime] = None,
 ) -> dict:
-    """Construct a Planetary Variable subscription source.
+    """Construct a subscription source.
 
-    Planetary Variables come in 4 types and are further subdivided
-    within these types. See [Subscribing to Planetary Variables](https://docs.planet.com/develop/apis/subscriptions/sources/#planetary-variable-and-analysis-ready-source-types)
-    or the [OpenAPI spec](https://api.planet.com/subscriptions/v1/spec) for
-    more details.
+    See [Subscribing to Planetary Variables and Analysis Ready sources](https://docs.planet.com/develop/apis/subscriptions/sources/#planetary-variable-and-analysis-ready-source-types)
+    or the [OpenAPI spec](https://api.planet.com/subscriptions/v1/spec) to learn more about different product options.
 
     The return value can be passed to
     [planet.subscription_request.build_request][].
 
     Note: this function does not validate variable types and ids.
 
     Parameters:
-        var_type: Planetary Variable type. See documentation for all
-            available types.  Used to be a required parameter but
-            is now optional and can be 'None'.
-        var_id: A Planetary Variable ID. See documenation for all
+        source_id: A source ID. See documenation for all
             available IDs.
         geometry: The area of interest of the subscription that will be
             used to determine matches. May be a geojson-like dict or a
@@ -315,8 +309,7 @@ def planetary_variable_source(
     Examples:
 
         ```python
-        pv_source = planetary_variables_source(
-            "soil_water_content",
+        pv_source = subscription_source(
             "SWC-AMSR2-C_V1.0_100",
             geometry={
                 "type": "Polygon",
@@ -343,7 +336,7 @@ def planetary_variable_source(
     # TODO: validation of variable types and ids.
 
     parameters = {
-        "id": var_id,
+        "id": source_id,
         "geometry": geojson.as_geom_or_ref(geometry),
     }
 
@@ -359,8 +352,6 @@ def planetary_variable_source(
             raise ClientError('Could not convert end_time to an iso string')
 
     source: dict[str, Any] = {"parameters": parameters}
-    if var_type:
-        source["type"] = var_type
     return source
 
 

tests/integration/test_subscriptions_cli.py

@@ -418,33 +418,25 @@ def test_subscriptions_results_csv(invoke):
     assert result.output.splitlines() == ["id,status", "1234-abcd,SUCCESS"]
 
 
-@pytest.mark.parametrize("geom, source_type",
-                         [("geom_geojson", "biomass_proxy"),
-                          ("geom_reference", None),
-                          ("str_geom_reference", None)])
-def test_request_pv_success(invoke, geom, source_type, request):
-    """Request-pv command succeeds"""
+@pytest.mark.parametrize("geom",
+                         [("geom_geojson"), ("geom_reference"),
+                          ("str_geom_reference")])
+def test_request_source_success(invoke, geom, request):
+    """Request-source command succeeds"""
     geom = request.getfixturevalue(geom)
     if isinstance(geom, dict):
         geom = json.dumps(geom)
     cmd = [
-        "request-pv",
-        "--var-id=BIOMASS-PROXY_V3.0_10",
+        "request-source",
+        "--source-id=BIOMASS-PROXY_V3.0_10",
         f"--geometry={geom}",
         "--start-time=2021-03-01T00:00:00",
     ]
 
-    if source_type:
-        cmd.append(f"--var-type={source_type}")
-
     result = invoke(cmd)
 
     assert result.exit_code == 0  # success.
     source = json.loads(result.output)
-    if source_type:
-        assert source["type"] == "biomass_proxy"
-    else:
-        assert "type" not in source
     assert source["parameters"]["id"] == "BIOMASS-PROXY_V3.0_10"
 
 

tests/unit/test_subscription_request.py

@@ -556,28 +556,22 @@ def test_toar_tool_success():
 
 
 @pytest.mark.parametrize(
-    "var_type, var_id",
+    "source_id",
     [
-        ("biomass_proxy", "BIOMASS-PROXY_V3.0_10"),  # actual real type and id.
-        ("var1", "VAR1-ABCD"),  # nonsense type and id
-        (None, "BIOMASS-PROXY_V3.0_10"),  # None type with valid id
+        ("BIOMASS-PROXY_V3.0_10"),  # actual valid id.
+        ("VAR1-ABCD"),  # nonsense id
     ])
-def test_pv_source_success(geom_geojson, var_type, var_id):
+def test_subscription_source_success(geom_geojson, source_id):
     """Configure a planetary variable subscription source."""
-    source = subscription_request.planetary_variable_source(
-        var_type,
-        var_id,
+    source = subscription_request.subscription_source(
+        source_id,
         geometry=geom_geojson,
         start_time=datetime(2021, 3, 1),
         end_time=datetime(2021, 3, 2),
     )
 
-    if var_type:
-        assert source["type"] == var_type
-    else:
-        assert "type" not in source
     params = source["parameters"]
-    assert params["id"] == var_id
+    assert params["id"] == source_id
     assert params["geometry"] == geom_geojson
     assert params["start_time"].startswith("2021-03-01")