Merge pull request #182 from planetlabs/analytics_pagination_defaults

1.3.1. Features pagination tweaks

Author: sarasafavi

CHANGES.txt

@@ -1,17 +1,18 @@
+1.3.1 (2019-07-19)
+-------------------------------------
+- Added default limit of 100 to `analytics collections features list`
+- Added separate `analytics collections features list-all` that will keep retrieving results with no limit
+- Added before, after options to both `analytics collections features list` and `analytics collections features list-all`
+
 1.3.0 (2019-07-10)
 -------------------------------------
 - Added support for Analytic Feeds
-
 - Fixing incorrect shorthand CLI arg
 - Add comment to explain why the get resource entrypoint won't work in AF next.
-- bump version
 - unit tests for analytics commands
 - Adding auto-pagination for analytics commands
-- Misc fixup for flake8 and test dependencies
 - Add additional mosaics entrypoints to list mosaics for a series, as well mosaics for AF resources
 - Separate out analytics configuration to allow for using analytics alongside mosaics, even in AF next
-- Flesh out analytics CLI entrypoints and client funcs
-- Stub out analytics entrypoints
 
 1.2.4 (2019-06-27)
 -------------------------------------

docs/source/cli/examples.rst

@@ -142,17 +142,35 @@ List all mosaics associated with a feed, subscription, or collection (if the fee
     planet analytics subscriptions list-mosaics <subscription_id>
     planet analytics collections list-mosaics <collection_id or subscription_id>
 
-Get all features (GeoJSON results) for a collection::
+Features (GeoJSON results) for a collection can be requested in one of two ways. The `list` option
+will only return slices of results (defaults to 100 at a time), whereas `list-all` will stream
+features until all features have been retrieved. Both options accept the same additional filters.
 
     planet analytics collections features list <collection_id or subscription_id>
+    planet analytics collections features list-all <collection_id or subscription_id>
 
-Get the first 500 features (GeoJSON results) for a collection within a certain time range::
+To page through results when using `list`::
 
-    planet analytics collections features list <collection_id or subscription_id> --time-range 2019-01-01T00:00:00.00Z/2019-02-01T00:00:00.00Z --limit 500
+    planet analytics collections features list <collection_id or subscription_id>
+    planet analytics collections features list <collection_id or subscription_id> --before <feature_id_of_last_feature_in_previous_page>
+
+Get the 10 most recent features (GeoJSON results) for a collection::
+
+    planet analytics collections features list <collection_id or subscription_id> --limit 10
+
+Stream all features (GeoJSON results) since last seen feature::
+
+    planet analytics collections features list-all <collection_id or subscription_id> --after <feature_id>
+
+Get features (GeoJSON results) for a collection within a certain time range::
+
+    planet analytics collections features list <collection_id or subscription_id> --time-range 2019-01-01T00:00:00.00Z/2019-02-01T00:00:00.00Z
+    planet analytics collections features list-all <collection_id or subscription_id> --time-range 2019-01-01T00:00:00.00Z/2019-02-01T00:00:00.00Z
 
-Get all features (GeoJSON results) for a collection within a certain area::
+Get features (GeoJSON results) for a collection within a certain area::
 
     planet analytics collections features list <collection_id or subscription_id> --bbox 122.3,47.6,122.4,47.7
+    planet analytics collections features list-all <collection_id or subscription_id> --bbox 122.3,47.6,122.4,47.7
 
 It is also possible to get resources associated with a particular GeoJSON feature in a collection.
 Just as different feeds are based upon different imagery types and produce different types of

planet/api/__version__.py

@@ -1 +1 @@
-__version__ = '1.3.0'
+__version__ = '1.3.1'

planet/api/client.py

@@ -443,22 +443,32 @@ def get_collection_info(self, subscription_id):
 
     def list_collection_features(self,
                                  subscription_id,
-                                 bbox,
-                                 time_range,
+                                 bbox=None,
+                                 time_range=None,
+                                 before=None,
+                                 after=None,
                                  ):
         '''
         List features for an analytic subscription.
         :param subscription_id:
         :param time_range str: ISO format datetime interval.
         :param bbox tuple: A lon_min, lat_min, lon_max, lat_max area to search
+        :param before str: return features published before item with given ID
+        :param after str: return features published after item with given ID
         :raises planet.api.exceptions.APIException: On API error.
         :returns: :py:Class:`planet.api.models.WFS3Features`
         '''
-        params = {
-            'time': time_range,
-        }
+        params = {}
+
         if bbox:
             params['bbox'] = ','.join([str(b) for b in bbox])
+        if time_range:
+            params['time'] = time_range
+        if before:
+            params['before'] = before
+        if after:
+            params['after'] = after
+
         url = self._url('collections/{}/items'.format(subscription_id))
         return self._get(url, models.WFS3Features, params=params).get_body()
 

planet/scripts/v1.py

@@ -571,7 +571,6 @@ def features():
 
 @features.command('list')
 @click.argument('subscription_id')
-@limit_option(None)
 @click.option('--bbox', type=BoundingBox(), help=(
         'Region to query as a comma-delimited string:'
         ' lon_min,lat_min,lon_max,lat_max'
@@ -585,15 +584,56 @@ def features():
         'items since the start of January 2019), 2019-01-01T00:00:00.00Z '
         '(instant)'
 ))
+@click.option('--before', type=str, help=(
+    'Get results published before the item with the provided ID.'
+))
+@click.option('--after', type=str, help=(
+    'Get results published after the item with the provided ID.'
+))
+@limit_option(100)
 @pretty
-def list_features(subscription_id, pretty, limit, rbox, bbox, time_range):
-    '''Request feature list for a particular subscription.'''
+def list_features(subscription_id, pretty, limit, rbox, bbox, time_range,
+                  before, after):
+    '''Request feature list for a particular subscription, 100 at a time.'''
     cl = analytics_client_v1()
     bbox = bbox or rbox
-    features = cl.list_collection_features(subscription_id, bbox, time_range)
+    features = cl.list_collection_features(subscription_id, bbox, time_range,
+                                           before, after)
     echo_json_response(features, pretty, limit)
 
 
+@features.command('list-all')
+@click.argument('subscription_id')
+@click.option('--bbox', type=BoundingBox(), help=(
+        'Region to query as a comma-delimited string:'
+        ' lon_min,lat_min,lon_max,lat_max'
+))
+@click.option('--rbox', type=BoundingBox(), help='Alias for --bbox')
+@click.option('--time-range', type=DateInterval(), help=(
+        'Time interval. Can be open or closed interval, start times are '
+        'inclusive and end times are exclusive: '
+        '2019-01-01T00:00:00.00Z/2019-02-01T00:00:00.00Z (Closed interval for '
+        'January 2019), 2019-01-01T00:00:00.00Z/.. (Open interval for all '
+        'items since the start of January 2019), 2019-01-01T00:00:00.00Z '
+        '(instant)'
+))
+@click.option('--before', type=str, help=(
+    'Get results published before the item with the provided ID.'
+))
+@click.option('--after', type=str, help=(
+    'Get results published after the item with the provided ID.'
+))
+@pretty
+def list_features_all(subscription_id, pretty, rbox, bbox, time_range, before,
+                      after):
+    '''Return every available feature for a particular subscription'''
+    cl = analytics_client_v1()
+    bbox = bbox or rbox
+    features = cl.list_collection_features(subscription_id, bbox, time_range,
+                                           before, after)
+    echo_json_response(features, pretty)
+
+
 @features.command('get')
 @click.argument('resource_type', type=click.Choice(
     ['source-image-info', 'target-quad', 'source-quad']))