Adding sort_keys

CHANGELOG.md

@@ -7,6 +7,9 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+# Adding sort keys by Ed olivares
+    feature that allows sort_keys to be passed into this Api up to the CMR. Used the valid sort_keys as of July 2023
+
 ## [0.8.0]
 ### Added
 - [pull/15](https://github.com/nasa/python_cmr/pull/15): New feature added to filter by granules within the circle around lat/lon

README.md

@@ -57,7 +57,7 @@ This library is broken into two classes, CollectionQuery and GranuleQuery. Each
 methods used to build a query for CMR. Not all parameters provided by the CMR API are covered by this version of
 python-cmr.
 
-The following methods are available to both collecton and granule queries:
+The following methods are available to both collection and granule queries:
 
     # search for granules matching a specific product/short_name
     >>> api.short_name("AST_L1T")
@@ -121,6 +121,10 @@ Granule searches support these methods (in addition to the shared methods above)
     >>> api.instrument("MODIS")
     >>> api.platform("Terra")
 
+    # filter by a sort_key note: sort_keys are require some other fields to find some existing granules before they can be sorted
+
+    >>> api.parameters(short_name="OMNO2", version="003", provider='GES_DISC', sort_key='-start_date')
+
 Collection searches support these methods (in addition to the shared methods above):
 
     # search for collections from a specific archive center
@@ -196,7 +200,7 @@ your parameters as keyword arguments:
 Note: the kwarg key should match the name of a method from the above examples, and the value should be a tuple if it's a
 parameter that requires multiple values.
 
-To inspect and retreive results from the API, the following methods are available:
+To inspect and retrieve results from the API, the following methods are available:
 
     # inspect the number of results the query will return without downloading the results
     >>> print(api.hits())

cmr/queries.py

@@ -673,6 +673,52 @@ def platform(self, platform=""):
         self.params['platform'] = platform
         return self
 
+
+    def sort_key(self, sort_key=""):
+        """
+        See
+        https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html#sorting-granule-results
+        for valid granule sort_keys
+
+        Filter some defined sort_key; 
+        use negative (-) for start_date and end_date to sort by ascending
+
+        :param sort_key: name of the sort key
+        :returns: Query instance
+        """
+
+        valid_sort_keys = [
+        'campaign',
+        'entry_title',
+        'dataset_id',
+        'data_size',
+        'end_date',
+        '-end_date'
+        'granule_ur',
+        'producer_granule_id'
+        'project',
+        'provider',
+        'readable_granule_name',
+        'short_name',
+        '-start_date',
+        'start_date',
+        'version',
+        'platform',
+        'instrument',
+        'sensor',
+        'day_night_flag',
+        'online_only',
+        'browsable',
+        'browse_only',
+        'cloud_cover',
+        'revision_date']
+        # also covers if empty string
+        if sort_key not in valid_sort_keys:
+            raise ValueError("Please provide a valid sort_key for granules query see https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html#sorting-granule-results for valid sort_keys")
+
+        self.params['sort_key'] = sort_key
+        return self
+
     def granule_ur(self, granule_ur=""):
         """
         Filter by the granules unique ID. Note this will result in at most one granule

tests/test_granule.py

@@ -23,6 +23,8 @@ class TestGranuleClass(unittest.TestCase):
     platform = "platform"
     granule_ur = "granule_ur"
 
+    sort_key="sort_key"
+
     def test_short_name(self):
         query = GranuleQuery()
         query.short_name(self.short_name_val)
@@ -273,6 +275,20 @@ def test_platform(self):
         self.assertIn(self.platform, query.params)
         self.assertEqual(query.params[self.platform], "1B")
 
+    def test_sort_key(self):
+        query = GranuleQuery()
+        # Various sort keys using this as an example
+        query.sort_key("-start_time")
+
+        self.assertIn(self.sort_key, query.params)
+        self.assertEqual(query.params[self.sort_key], "-start_time")
+
+    def test_sort_key(self):
+        query = GranuleQuery()
+        with self.assertRaises(ValueError):
+            query.sort_key(None)
+
+
     def test_empty_platform(self):
         query = GranuleQuery()