Add support for fields parameter in Search and Admin APIs

Author: const-cloudinary

cloudinary/api.py

@@ -77,32 +77,30 @@ def resources(**options):
     uri = ["resources", resource_type]
     if upload_type:
         uri.append(upload_type)
-    params = only(options, "next_cursor", "max_results", "prefix", "tags",
-                  "context", "moderations", "direction", "start_at", "metadata")
+    params = __list_resources_params(**options)
+    params.update(only(options, "prefix", "start_at"))
     return call_api("get", uri, params, **options)
 
 
 def resources_by_tag(tag, **options):
     resource_type = options.pop("resource_type", "image")
     uri = ["resources", resource_type, "tags", tag]
-    params = only(options, "next_cursor", "max_results", "tags",
-                  "context", "moderations", "direction", "metadata")
+    params = __list_resources_params(**options)
     return call_api("get", uri, params, **options)
 
 
 def resources_by_moderation(kind, status, **options):
     resource_type = options.pop("resource_type", "image")
     uri = ["resources", resource_type, "moderations", kind, status]
-    params = only(options, "next_cursor", "max_results", "tags",
-                  "context", "moderations", "direction", "metadata")
+    params = __list_resources_params(**options)
     return call_api("get", uri, params, **options)
 
 
 def resources_by_ids(public_ids, **options):
     resource_type = options.pop("resource_type", "image")
     upload_type = options.pop("type", "upload")
     uri = ["resources", resource_type, upload_type]
-    params = dict(only(options, "tags", "moderations", "context"), public_ids=public_ids)
+    params = dict(__resources_params(**options), public_ids=public_ids)
     return call_api("get", uri, params, **options)
 
 
@@ -118,7 +116,7 @@ def resources_by_asset_folder(asset_folder, **options):
     :rtype:             Response
     """
     uri = ["resources", "by_asset_folder"]
-    params = only(options, "max_results", "tags", "moderations", "context", "next_cursor")
+    params = __list_resources_params(**options)
     params["asset_folder"] = asset_folder
     return call_api("get", uri, params, **options)
 
@@ -138,7 +136,7 @@ def resources_by_asset_ids(asset_ids, **options):
     :rtype:             Response
     """
     uri = ["resources", 'by_asset_ids']
-    params = dict(only(options, "tags", "moderations", "context"), asset_ids=asset_ids)
+    params = dict(__resources_params(**options), asset_ids=asset_ids)
     return call_api("get", uri, params, **options)
 
 
@@ -160,14 +158,42 @@ def resources_by_context(key, value=None, **options):
     """
     resource_type = options.pop("resource_type", "image")
     uri = ["resources", resource_type, "context"]
-    params = only(options, "next_cursor", "max_results", "tags",
-                  "context", "moderations", "direction", "metadata")
+    params = __list_resources_params(**options)
     params["key"] = key
     if value is not None:
         params["value"] = value
     return call_api("get", uri, params, **options)
 
 
+def __resources_params(**options):
+    """
+       Prepares optional parameters for resources_* API calls.
+
+       :param options: Additional options
+       :return: Optional parameters
+
+       :internal
+       """
+    params = only(options, "tags", "context", "metadata", "moderations")
+    params["fields"] = options.get("fields") and utils.encode_list(utils.build_array(options["fields"]))
+    return params
+
+
+def __list_resources_params(**options):
+    """
+       Prepares optional parameters for resources_* API calls.
+
+       :param options: Additional options
+       :return: Optional parameters
+
+       :internal
+       """
+    resources_params = __resources_params(**options)
+    resources_params.update(only(options, "next_cursor", "max_results", "direction"))
+
+    return resources_params
+
+
 def visual_search(image_url=None, image_asset_id=None, text=None, image_file=None, **options):
     """
     Find images based on their visual content.

cloudinary/search.py

@@ -3,8 +3,8 @@
 
 import cloudinary
 from cloudinary.api_client.call_api import call_json_api
-from cloudinary.utils import unique, unsigned_download_url_prefix, build_distribution_domain, base64url_encode, \
-    json_encode, compute_hex_hash, SIGNATURE_SHA256
+from cloudinary.utils import (unique, build_distribution_domain, base64url_encode, json_encode, compute_hex_hash,
+                              SIGNATURE_SHA256, build_array)
 
 
 class Search(object):
@@ -16,6 +16,7 @@ class Search(object):
         'sort_by': lambda x: next(iter(x)),
         'aggregate': None,
         'with_field': None,
+        'fields': None,
     }
 
     _ttl = 300  # Used for search URLs
@@ -57,6 +58,11 @@ def with_field(self, value):
         self._add("with_field", value)
         return self
 
+    def fields(self, value):
+        """Request which fields to return in the result set."""
+        self._add("fields", value)
+        return self
+
     def ttl(self, ttl):
         """
         Sets the time to live of the search URL.
@@ -133,5 +139,5 @@ def endpoint(self, endpoint):
     def _add(self, name, value):
         if name not in self.query:
             self.query[name] = []
-        self.query[name].append(value)
+        self.query[name].extend(build_array(value))
         return self

cloudinary/utils.py

@@ -186,7 +186,7 @@ def compute_hex_hash(s, algorithm=SIGNATURE_SHA1):
 
 
 def build_array(arg):
-    if isinstance(arg, list):
+    if isinstance(arg, (list, tuple)):
         return arg
     elif arg is None:
         return []
@@ -602,6 +602,7 @@ def normalize_params(params):
 
     return dict([(k, __bool_string(v)) for (k, v) in params.items() if v is not None and not v == ""])
 
+
 def sign_request(params, options):
     api_key = options.get("api_key", cloudinary.config().api_key)
     if not api_key:

test/test_api.py

@@ -205,6 +205,24 @@ def test05_resources_prefix(self, mocker):
         self.assertTrue(get_params(mocker)['context'])
         self.assertTrue(get_params(mocker)['tags'])
 
+    @patch(URLLIB3_REQUEST)
+    @unittest.skipUnless(cloudinary.config().api_secret, "requires api_key/api_secret")
+    def test06_resources_fields(self, mocker):
+        """ should allow listing resources and returning only specified fields """
+        mocker.return_value = MOCK_RESPONSE
+        api.resources(fields=["tags", "secure_url"], type="upload")
+
+        self.assertTrue(get_uri(mocker).endswith('/resources/image/upload'))
+        self.assertEqual(get_params(mocker)['fields'], "tags,secure_url")
+
+        api.resources(fields="context,url", type="upload")
+
+        self.assertEqual(get_params(mocker)['fields'], "context,url")
+
+        api.resources(fields="", type="upload")
+
+        self.assertNotIn('fields', get_params(mocker))
+
     @patch(URLLIB3_REQUEST)
     @unittest.skipUnless(cloudinary.config().api_secret, "requires api_key/api_secret")
     def test06_resources_tag(self, mocker):
@@ -979,8 +997,6 @@ def test_delete_folder(self, mocker):
 
         api.delete_folder(UNIQUE_TEST_FOLDER)
 
-        
-
         self.assertEqual("DELETE", get_method(mocker))
         self.assertTrue(get_uri(mocker).endswith('/folders/' + UNIQUE_TEST_FOLDER))
 

test/test_search.py

@@ -212,10 +212,13 @@ def test_should_not_duplicate_values(self, mocker):
             .sort_by('created_at') \
             .aggregate('format') \
             .aggregate('format') \
-            .aggregate('resource_type') \
+            .aggregate(['resource_type', 'type']) \
             .with_field('context') \
             .with_field('context') \
             .with_field('tags') \
+            .fields(('tags', 'context')) \
+            .fields('metadata') \
+            .fields('tags') \
             .execute()
 
         _, args = mocker.call_args
@@ -226,8 +229,9 @@ def test_should_not_duplicate_values(self, mocker):
                 {'created_at': 'desc'},
                 {'public_id': 'asc'},
             ],
-            'aggregate': ['format', 'resource_type'],
+            'aggregate': ['format', 'resource_type', 'type'],
             'with_field': ['context', 'tags'],
+            'fields': ['tags', 'context', 'metadata'],
         })
 
     def test_should_build_search_url(self):