planet 2.6.dev0__tar.gz → 2.7__tar.gz

{planet-2.6.dev0 → planet-2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: planet
-Version: 2.6.dev0
+Version: 2.7
 Summary: Planet SDK for Python
 Home-page: https://github.com/planetlabs/planet-client-python
 Author: Jennifer Reiber Kyle

planet-2.7/planet/__version__.py

@@ -0,0 +1 @@
+__version__ = '2.7'

{planet-2.6.dev0 → planet-2.7}/planet/cli/data.py

@@ -15,7 +15,6 @@
 from typing import List, Optional
 from contextlib import asynccontextmanager
 from pathlib import Path
-
 import click
 
 from planet.reporting import AssetStatusBar
@@ -37,6 +36,7 @@ from .cmds import coro, translate_exceptions
 from .io import echo_json
 from .options import limit, pretty
 from .session import CliSession
+from .validators import check_geom
 
 valid_item_string = "Valid entries for ITEM_TYPES: " + "|".join(
     get_data_item_types())
@@ -281,6 +281,7 @@ def filter(ctx,
 @click.argument("item_types",
                 type=types.CommaSeparatedString(),
                 callback=check_item_types)
+@click.option("--geom", type=types.Geometry(), callback=check_geom)
 @click.option('--filter',
               type=types.JSON(),
               help="""Apply specified filter to search. Can be a json string,
@@ -293,7 +294,7 @@ def filter(ctx,
               show_default=True,
               help='Field and direction to order results by.')
 @pretty
-async def search(ctx, item_types, filter, limit, name, sort, pretty):
+async def search(ctx, item_types, geom, filter, limit, name, sort, pretty):
     """Execute a structured item search.
 
     This function outputs a series of GeoJSON descriptions, one for each of the
@@ -311,6 +312,7 @@ async def search(ctx, item_types, filter, limit, name, sort, pretty):
     async with data_client(ctx) as cl:
 
         async for item in cl.search(item_types,
+                                    geometry=geom,
                                     search_filter=filter,
                                     name=name,
                                     sort=sort,
@@ -325,6 +327,7 @@ async def search(ctx, item_types, filter, limit, name, sort, pretty):
 @click.argument("item_types",
                 type=types.CommaSeparatedString(),
                 callback=check_item_types)
+@click.option("--geom", type=types.Geometry(), callback=check_geom)
 @click.option(
     '--filter',
     type=types.JSON(),
@@ -339,7 +342,13 @@ async def search(ctx, item_types, filter, limit, name, sort, pretty):
               is_flag=True,
               help='Send a daily email when new results are added.')
 @pretty
-async def search_create(ctx, item_types, filter, name, daily_email, pretty):
+async def search_create(ctx,
+                        item_types,
+                        geom,
+                        filter,
+                        name,
+                        daily_email,
+                        pretty):
     """Create a new saved structured item search.
 
     This function outputs a full JSON description of the created search,
@@ -349,6 +358,7 @@ async def search_create(ctx, item_types, filter, name, daily_email, pretty):
     """
     async with data_client(ctx) as cl:
         items = await cl.create_search(item_types=item_types,
+                                       geometry=geom,
                                        search_filter=filter,
                                        name=name,
                                        enable_email=daily_email)
@@ -485,6 +495,10 @@ async def search_delete(ctx, search_id):
               type=str,
               required=True,
               help='Name of the saved search.')
+@click.option("--geom",
+              type=types.Geometry(),
+              callback=check_geom,
+              default=None)
 @click.option('--daily-email',
               is_flag=True,
               help='Send a daily email when new results are added.')
@@ -493,6 +507,7 @@ async def search_update(ctx,
                         search_id,
                         item_types,
                         filter,
+                        geom,
                         name,
                         daily_email,
                         pretty):
@@ -504,9 +519,10 @@ async def search_update(ctx,
     async with data_client(ctx) as cl:
         items = await cl.update_search(search_id,
                                        item_types,
-                                       filter,
-                                       name,
-                                       daily_email)
+                                       search_filter=filter,
+                                       name=name,
+                                       geometry=geom,
+                                       enable_email=daily_email)
         echo_json(items, pretty)
 
 

{planet-2.6.dev0 → planet-2.7}/planet/cli/subscriptions.py

@@ -13,6 +13,7 @@ from planet.clients.subscriptions import SubscriptionsClient
 from .. import subscription_request
 from ..subscription_request import sentinel_hub
 from ..specs import get_item_types, validate_item_type, SpecificationException
+from .validators import check_geom
 
 ALL_ITEM_TYPES = get_item_types()
 valid_item_string = "Valid entries for ITEM_TYPES: " + "|".join(ALL_ITEM_TYPES)
@@ -346,7 +347,8 @@ def request(name,
 @click.option(
     '--geometry',
     required=True,
-    type=types.JSON(),
+    type=types.Geometry(),
+    callback=check_geom,
     help="""Geometry of the area of interest of the subscription that will be
     used to determine matches. Can be a string, filename, or - for stdin.""")
 @click.option('--start-time',
@@ -406,6 +408,7 @@ def request_catalog(item_types,
     required=True,
     help='Planetary variable type.',
     type=click.Choice([
+        "analysis_ready_ps",
         "biomass_proxy",
         "land_surface_temperature",
         "soil_water_content",
@@ -418,7 +421,8 @@ def request_catalog(item_types,
 @click.option(
     '--geometry',
     required=True,
-    type=types.JSON(),
+    type=types.Geometry(),
+    callback=check_geom,
     help="""Geometry of the area of interest of the subscription that will be
     used to determine matches. Can be a string, filename, or - for stdin.""")
 @click.option('--start-time',

{planet-2.6.dev0 → planet-2.7}/planet/cli/types.py

@@ -93,6 +93,20 @@ class JSON(click.ParamType):
         return convdict
 
 
+class Geometry(click.ParamType):
+    name = 'geom'
+
+    def __init__(self):
+        self.types = [JSON(), CommaSeparatedString()]
+
+    def convert(self, value, param, ctx):
+        for type in self.types:
+            try:
+                return type.convert(value, param, ctx)
+            except click.BadParameter:
+                continue
+
+
 class Field(click.ParamType):
     """Clarify that this entry is for a field"""
     name = 'field'

planet-2.7/planet/cli/validators.py

@@ -0,0 +1,27 @@
+# Copyright 2022 Planet Labs, PBC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+"""CLI Parameter validation"""
+from typing import Optional
+from planet import geojson
+
+
+def check_geom(ctx, param, geometry) -> Optional[dict]:
+    """Validates geometry as GeoJSON or feature ref(s)."""
+    if isinstance(geometry, dict):
+        return geojson.as_geom_or_ref(geometry)
+    geoms = {}
+    if geometry:
+        for geom in geometry:
+            geoms.update(geojson.as_geom_or_ref(geom))
+    return geoms if geoms else None

{planet-2.6.dev0 → planet-2.7}/planet/clients/data.py

@@ -26,6 +26,7 @@ from ..constants import PLANET_BASE_URL
 from ..http import Session
 from ..models import Paged, StreamingBody
 from ..specs import validate_data_item_type
+from ..geojson import as_geom_or_ref
 
 BASE_URL = f'{PLANET_BASE_URL}/data/v1/'
 SEARCHES_PATH = '/searches'
@@ -112,6 +113,7 @@ class DataClient:
 
     async def search(self,
                      item_types: List[str],
+                     geometry: Optional[dict] = None,
                      search_filter: Optional[dict] = None,
                      name: Optional[str] = None,
                      sort: Optional[str] = None,
@@ -134,6 +136,8 @@ class DataClient:
             sort: Field and direction to order results by. Valid options are
             given in SEARCH_SORT.
             name: The name of the saved search.
+            geometry: GeoJSON, a feature reference or a list of feature
+                references
             limit: Maximum number of results to return. When set to 0, no
                 maximum is applied.
 
@@ -149,6 +153,9 @@ class DataClient:
 
         item_types = [validate_data_item_type(item) for item in item_types]
         request_json = {'filter': search_filter, 'item_types': item_types}
+
+        if geometry:
+            request_json['geometry'] = as_geom_or_ref(geometry)
         if name:
             request_json['name'] = name
 
@@ -159,7 +166,6 @@ class DataClient:
                 raise exceptions.ClientError(
                     f'{sort} must be one of {SEARCH_SORT}')
             params['_sort'] = sort
-
         response = await self._session.request(method='POST',
                                                url=url,
                                                json=request_json,
@@ -171,6 +177,7 @@ class DataClient:
                             item_types: List[str],
                             search_filter: dict,
                             name: str,
+                            geometry: Optional[dict] = None,
                             enable_email: bool = False) -> dict:
         """Create a new saved structured item search.
 
@@ -192,6 +199,7 @@ class DataClient:
 
         Parameters:
             item_types: The item types to include in the search.
+            geometry: A feature reference or a GeoJSON
             search_filter: Structured search criteria.
             name: The name of the saved search.
             enable_email: Send a daily email when new results are added.
@@ -205,12 +213,15 @@ class DataClient:
         url = self._searches_url()
 
         item_types = [validate_data_item_type(item) for item in item_types]
+
         request = {
             'name': name,
             'filter': search_filter,
             'item_types': item_types,
             '__daily_email_enabled': enable_email
         }
+        if geometry:
+            request['geometry'] = as_geom_or_ref(geometry)
 
         response = await self._session.request(method='POST',
                                                url=url,
@@ -222,12 +233,14 @@ class DataClient:
                             item_types: List[str],
                             search_filter: dict,
                             name: str,
+                            geometry: Optional[dict] = None,
                             enable_email: bool = False) -> dict:
         """Update an existing saved search.
 
         Parameters:
             search_id: Saved search identifier.
             item_types: The item types to include in the search.
+            geometry: A feature reference or a GeoJSON
             search_filter: Structured search criteria.
             name: The name of the saved search.
             enable_email: Send a daily email when new results are added.
@@ -238,12 +251,15 @@ class DataClient:
         url = f'{self._searches_url()}/{search_id}'
 
         item_types = [validate_data_item_type(item) for item in item_types]
+
         request = {
             'name': name,
             'filter': search_filter,
             'item_types': item_types,
             '__daily_email_enabled': enable_email
         }
+        if geometry:
+            request['geometry'] = geometry
 
         response = await self._session.request(method='PUT',
                                                url=url,

{planet-2.6.dev0 → planet-2.7}/planet/data_filter.py

@@ -238,9 +238,10 @@ def geometry_filter(geom: dict) -> dict:
         geom: GeoJSON describing the filter geometry, feature, or feature
             collection.
     """
-    return _field_filter('GeometryFilter',
-                         field_name='geometry',
-                         config=geojson.as_geom(geom))
+    geom_filter = _field_filter('GeometryFilter',
+                                field_name='geometry',
+                                config=geojson.validate_geom_as_geojson(geom))
+    return geom_filter
 
 
 def number_in_filter(field_name: str, values: List[float]) -> dict:

{planet-2.6.dev0 → planet-2.7}/planet/exceptions.py

@@ -90,3 +90,7 @@ class PagingError(ClientError):
 
 class GeoJSONError(ClientError):
     """Errors that occur due to invalid GeoJSON"""
+
+
+class FeatureError(ClientError):
+    """Errors that occur due to incorrectly formatted feature reference"""

{planet-2.6.dev0 → planet-2.7}/planet/geojson.py

@@ -12,23 +12,22 @@
 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 # License for the specific language governing permissions and limitations under
 # the License.
-"""Functionality for interacting with GeoJSON."""
+"""Functionality for interacting with GeoJSON and planet references."""
 import json
 import logging
 import typing
 
 import geojson as gj
 from jsonschema import Draft7Validator
-
 from .constants import DATA_DIR
-from .exceptions import GeoJSONError
+from .exceptions import GeoJSONError, FeatureError
 
-GEOJSON_TYPES = ['Feature']
+GEOJSON_TYPES = ["Feature"]
 
 LOGGER = logging.getLogger(__name__)
 
 
-def as_geom(data: dict) -> dict:
+def as_geom_or_ref(data) -> dict:
     """Extract the geometry from GeoJSON and validate.
 
     Parameters:
@@ -42,13 +41,65 @@ def as_geom(data: dict) -> dict:
             or FeatureCollection or if more than one Feature is in a
             FeatureCollection.
     """
-    geom = geom_from_geojson(data)
-    validate_geom(geom)
-    return geom
+    if isinstance(data, str):
+        return as_ref(data)
+    geom_type = data['type']
+    if geom_type == 'ref':
+        return as_ref(data)
+    else:
+        geom = geom_from_geojson(data)
+        validate_geom_as_geojson(geom)
+        return geom
+
+
+def validate_ref(uri) -> bool:
+    if uri is None:
+        raise FeatureError("Expected str, not None")
+    parts = uri.split("/", 4)
+    if parts[0] != "pl:features":
+        raise FeatureError("Expected scheme pl:features")
+    path = parts[1:]
+    if len(path) < 2:
+        raise FeatureError("Expceted dataset/collection path")
+    return True
+
+
+def convert_ref_to_dict(data: str) -> dict:
+    """ Ensure geom reference is in the expected format
+        Then convert it into a geometry block
+
+    Parameters:
+        data: str, a feature reference
+    Returns:
+        GeoJSON geometry reference
+    """
+    if validate_ref(data):
+        geom = {
+            "type": "ref",
+            "content": data,
+        }
+        return geom
+    return dict()
+
+
+def as_ref(data) -> dict:
+    if isinstance(data, str):
+        data = convert_ref_to_dict(data)
+    if isinstance(data, dict):
+        geom_type = data['type']
+        if geom_type.lower() != 'ref':
+            raise FeatureError(
+                f'Invalid geometry reference: {geom_type} is not a reference (the type should be "ref").'
+            )
+        if "content" not in data:
+            raise FeatureError(
+                'Invalid geometry reference: Missing content block that contains the reference.'
+            )
+    return data
 
 
 def as_polygon(data: dict) -> dict:
-    geom = as_geom(data)
+    geom = as_geom_or_ref(data)
     geom_type = geom['type']
     if geom_type.lower() != 'polygon':
         raise GeoJSONError(
@@ -75,7 +126,7 @@ def geom_from_geojson(data: dict) -> dict:
     else:
         try:
             # feature
-            ret = as_geom(data['geometry'])
+            ret = as_geom_or_ref(data['geometry'])
         except KeyError:
             try:
                 # FeatureCollection
@@ -88,11 +139,11 @@ def geom_from_geojson(data: dict) -> dict:
                     'FeatureCollection has multiple features. Only one feature'
                     ' can be used to get geometry.')
 
-            ret = as_geom(features[0])
+            ret = as_geom_or_ref(features[0])
     return ret
 
 
-def validate_geom(data: dict):
+def validate_geom_as_geojson(data: dict):
     """Validate GeoJSON geometry.
 
     Parameters:
@@ -101,23 +152,26 @@ def validate_geom(data: dict):
     Raises:
         planet.exceptions.GeoJSONError: If data is not a valid GeoJSON
         geometry.
+    Returns:
+        GeoJSON
     """
+    data = geom_from_geojson(data)
     if 'type' not in data:
-        raise GeoJSONError("Missing 'type' key.")
+        raise GeoJSONError('Missing "type" key.')
     if 'coordinates' not in data:
-        raise GeoJSONError("Missing 'coordinates' key.")
+        raise GeoJSONError('Missing "coordinates" key.')
 
     try:
-        cls = getattr(gj, data["type"])
-        obj = cls(data["coordinates"])
+        cls = getattr(gj, data['type'])
+        obj = cls(data['coordinates'])
         if not obj.is_valid:
             raise GeoJSONError(obj.errors())
     except AttributeError as err:
-        raise GeoJSONError("Not a GeoJSON geometry type") from err
+        raise GeoJSONError('Not a GeoJSON geometry type') from err
     except ValueError as err:
-        raise GeoJSONError("Not a GeoJSON coordinate value") from err
+        raise GeoJSONError('Not a GeoJSON coordinate value') from err
 
-    return
+    return data
 
 
 def as_featurecollection(features: typing.List[dict]) -> dict:

{planet-2.6.dev0 → planet-2.7}/planet/order_request.py

@@ -356,9 +356,9 @@ def clip_tool(aoi: dict) -> dict:
         planet.exceptions.ClientError: If GeoJSON is not a valid polygon or
             multipolygon.
     """
-    valid_types = ['Polygon', 'MultiPolygon']
+    valid_types = ['Polygon', 'MultiPolygon', 'ref']
 
-    geom = geojson.as_geom(aoi)
+    geom = geojson.as_geom_or_ref(aoi)
     if geom['type'].lower() not in [v.lower() for v in valid_types]:
         raise ClientError(
             f'Invalid geometry type: {geom["type"]} is not in {valid_types}.')

{planet-2.6.dev0 → planet-2.7}/planet/subscription_request.py

@@ -167,7 +167,7 @@ def build_request(name: str,
 def catalog_source(
     item_types: List[str],
     asset_types: List[str],
-    geometry: Mapping,
+    geometry: dict,
     start_time: datetime,
     filter: Optional[Mapping] = None,
     end_time: Optional[datetime] = None,
@@ -250,7 +250,7 @@ def catalog_source(
     parameters = {
         "item_types": item_types,
         "asset_types": asset_types,
-        "geometry": geojson.as_geom(dict(geometry)),
+        "geometry": geojson.as_geom_or_ref(geometry),
     }
 
     try:
@@ -280,14 +280,15 @@ def catalog_source(
 
 
 def planetary_variable_source(
-    var_type: Literal["biomass_proxy",
+    var_type: Literal["analysis_ready_ps",
+                      "biomass_proxy",
                       "land_surface_temperature",
                       "soil_water_content",
                       "vegetation_optical_depth",
                       "forest_carbon_diligence_30m",
                       "field_boundaries_sentinel_2_p1m"],
     var_id: str,
-    geometry: Mapping,
+    geometry: dict,
     start_time: datetime,
     end_time: Optional[datetime] = None,
 ) -> dict:
@@ -304,9 +305,10 @@ def planetary_variable_source(
     Note: this function does not validate variable types and ids.
 
     Parameters:
-        var_type: one of "biomass_proxy", "land_surface_temperature",
-            "soil_water_content", "vegetation_optical_depth",
-            "forest_carbon_diligence_30m, or field_boundaries_sentinel_2_p1m".
+        var_type: one of "analysis_ready_ps", "biomass_proxy",
+            "land_surface_temperature", "soil_water_content",
+            "vegetation_optical_depth", "forest_carbon_diligence_30m,
+            or field_boundaries_sentinel_2_p1m".
         var_id: a value such as "SWC-AMSR2-C_V1.0_100" for soil water
             content derived from AMSR2 C band.
         geometry: The area of interest of the subscription that will be
@@ -355,7 +357,7 @@ def planetary_variable_source(
 
     parameters = {
         "id": var_id,
-        "geometry": geojson.as_geom(dict(geometry)),
+        "geometry": geojson.as_geom_or_ref(geometry),
     }
 
     try:
@@ -596,9 +598,9 @@ def clip_tool(aoi: Mapping) -> dict:
         planet.exceptions.ClientError: If aoi is not a valid polygon or
             multipolygon.
     """
-    valid_types = ['Polygon', 'MultiPolygon']
+    valid_types = ['Polygon', 'MultiPolygon', 'ref']
 
-    geom = geojson.as_geom(dict(aoi))
+    geom = geojson.as_geom_or_ref(dict(aoi))
     if geom['type'].lower() not in [v.lower() for v in valid_types]:
         raise ClientError(
             f'Invalid geometry type: {geom["type"]} is not in {valid_types}.')

{planet-2.6.dev0 → planet-2.7}/planet.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: planet
-Version: 2.6.dev0
+Version: 2.7
 Summary: Planet SDK for Python
 Home-page: https://github.com/planetlabs/planet-client-python
 Author: Jennifer Reiber Kyle

{planet-2.6.dev0 → planet-2.7}/planet.egg-info/SOURCES.txt

@@ -35,6 +35,7 @@ planet/cli/orders.py
 planet/cli/session.py
 planet/cli/subscriptions.py
 planet/cli/types.py
+planet/cli/validators.py
 planet/clients/__init__.py
 planet/clients/data.py
 planet/clients/orders.py

planet-2.6.dev0/planet/__version__.py

@@ -1 +0,0 @@
-__version__ = '2.6dev'