Add download_backedup_asset helper method

Add `versions` parameter to `resource` Admin API
Add `versions` parameter to `restore` Admin API

Author: const-cloudinary

cloudinary/api.py

@@ -105,7 +105,7 @@ def resource(public_id, **options):
     uri = ["resources", resource_type, upload_type, public_id]
     params = only(options, "exif", "faces", "colors", "image_metadata", "cinemagraph_analysis",
                   "pages", "phash", "coordinates", "max_results", "quality_analysis", "derived_next_cursor",
-                  "accessibility_analysis")
+                  "accessibility_analysis", "versions")
     return call_api("get", uri, params, **options)
 
 
@@ -335,8 +335,8 @@ def restore(public_ids, **options):
     resource_type = options.pop("resource_type", "image")
     upload_type = options.pop("type", "upload")
     uri = ["resources", resource_type, upload_type, "restore"]
-    params = dict(public_ids=public_ids)
-    return call_api("post", uri, params, **options)
+    params = dict(public_ids=public_ids, **only(options, "versions"))
+    return call_json_api("post", uri, params, **options)
 
 
 def upload_mappings(**options):

cloudinary/api_client/call_api.py

@@ -22,11 +22,9 @@ def call_metadata_api(method, uri, params, **options):
     return call_json_api(method, uri, params, **options)
 
 
-def call_json_api(method, uri, jsonBody, **options):
-    logger.debug(jsonBody)
-    data = json.dumps(jsonBody).encode('utf-8')
-    return _call_api(method, uri, body=data,
-                     headers={'Content-Type': 'application/json'}, **options)
+def call_json_api(method, uri, json_body, **options):
+    data = json.dumps(json_body).encode('utf-8')
+    return _call_api(method, uri, body=data, headers={'Content-Type': 'application/json'}, **options)
 
 
 def call_api(method, uri, params, **options):

cloudinary/utils.py

@@ -15,10 +15,10 @@
 from datetime import datetime, date
 from fractions import Fraction
 from numbers import Number
-from urllib3 import ProxyManager, PoolManager
 
 import six.moves.urllib.parse
 from six import iteritems
+from urllib3 import ProxyManager, PoolManager
 
 import cloudinary
 from cloudinary import auth_token
@@ -726,15 +726,23 @@ def cloudinary_url(source, **options):
     return source, options
 
 
-def cloudinary_api_url(action='upload', **options):
-    cloudinary_prefix = options.get("upload_prefix", cloudinary.config().upload_prefix)\
+def base_api_url(path, **options):
+    cloudinary_prefix = options.get("upload_prefix", cloudinary.config().upload_prefix) \
                         or "https://api.cloudinary.com"
     cloud_name = options.get("cloud_name", cloudinary.config().cloud_name)
+
     if not cloud_name:
         raise ValueError("Must supply cloud_name")
+
+    path = build_array(path)
+
+    return encode_unicode_url("/".join([cloudinary_prefix, cloudinary.API_VERSION, cloud_name] + path))
+
+
+def cloudinary_api_url(action='upload', **options):
     resource_type = options.get("resource_type", "image")
 
-    return encode_unicode_url("/".join([cloudinary_prefix, "v1_1", cloud_name, resource_type, action]))
+    return base_api_url([resource_type, action], **options)
 
 
 def cloudinary_scaled_url(source, width, transformation, options):
@@ -848,6 +856,31 @@ def download_zip_url(**options):
     return download_archive_url(**new_options)
 
 
+def download_backedup_asset(asset_id, version_id, **options):
+    """
+    The returned url allows downloading the backedup asset based on the the asset ID and the version ID.
+
+    Parameters asset_id and version_id are returned with api.resource(<PUBLIC_ID1>, versions=True) API call.
+
+    :param  asset_id:   The asset ID of the asset.
+    :type   asset_id:   str
+    :param  version_id: The version ID of the asset.
+    :type   version_id: str
+    :param  options:    Additional options.
+    :type   options:    dict, optional
+    :return:The signed URL for downloading backup version of the asset.
+    :rtype: str
+    """
+    params = {
+        "timestamp": options.get("timestamp", now()),
+        "asset_id": asset_id,
+        "version_id": version_id
+    }
+    cloudinary_params = sign_request(params, options)
+
+    return base_api_url("download_backup", **options) + "?" + urlencode(bracketize_seq(cloudinary_params), True)
+
+
 def generate_auth_token(**options):
     token_options = merge(cloudinary.config().auth_token, options)
     return auth_token.generate(**token_options)

test/helper_test.py

@@ -1,4 +1,5 @@
 # -*- coding: latin-1 -*-
+import json
 from contextlib import contextmanager
 import os
 import random
@@ -67,6 +68,10 @@ def get_params(args):
     return args[2] or {}
 
 
+def get_json_body(mocker):
+    return json.loads(mocker.call_args[1]["body"].decode('utf-8') or {})
+
+
 def get_param(mocker, name):
     """
     Return the value of the parameter

test/test_api.py

@@ -10,7 +10,7 @@
 from cloudinary import api, uploader, utils
 from test.helper_test import SUFFIX, TEST_IMAGE, get_uri, get_params, get_list_param, get_param, TEST_DOC, get_method, \
     UNIQUE_TAG, api_response_mock, ignore_exception, cleanup_test_resources_by_tag, cleanup_test_transformation, \
-    cleanup_test_resources, UNIQUE_TEST_FOLDER, EVAL_STR
+    cleanup_test_resources, UNIQUE_TEST_FOLDER, EVAL_STR, get_json_body
 from cloudinary.exceptions import BadRequest, NotFound
 
 MOCK_RESPONSE = api_response_mock()
@@ -230,7 +230,20 @@ def test07b_resource_allows_derived_next_cursor_parameter(self, mocker):
         api.resource(API_TEST_ID, derived_next_cursor=NEXT_CURSOR)
         args, kwargs = mocker.call_args
         self.assertTrue("derived_next_cursor" in get_params(args))
-    
+
+    @patch('urllib3.request.RequestMethods.request')
+    @unittest.skipUnless(cloudinary.config().api_secret, "requires api_key/api_secret")
+    def test07c_resource_allows_versions(self, mocker):
+        """ should allow versions parameter """
+        mocker.return_value = MOCK_RESPONSE
+
+        api.resource(API_TEST_ID, versions=True)
+
+        params = get_params(mocker.call_args[0])
+
+        self.assertIn("versions", params)
+        self.assertTrue(params["versions"])
+
     @patch('urllib3.request.RequestMethods.request')
     @unittest.skipUnless(cloudinary.config().api_secret, "requires api_key/api_secret")
     def test08_delete_derived(self, mocker):
@@ -757,6 +770,21 @@ def test_restore(self):
         self.assertNotEqual(resource, None)
         self.assertEqual(resource["bytes"], 3381)
 
+    @patch('urllib3.request.RequestMethods.request')
+    @unittest.skipUnless(cloudinary.config().api_secret, "requires api_key/api_secret")
+    def test_restore_versions(self, mocker):
+        mocker.return_value = MOCK_RESPONSE
+
+        public_ids = ["pub1", "pub2"]
+        versions = ["ver1", "ver2"]
+
+        api.restore(public_ids, versions=versions)
+
+        json_body = get_json_body(mocker)
+
+        self.assertListEqual(public_ids, json_body["public_ids"])
+        self.assertListEqual(versions, json_body["versions"])
+
     @unittest.skipUnless(cloudinary.config().api_secret, "requires api_key/api_secret")
     def test_upload_mapping(self):
 

test/test_archive.py

@@ -111,6 +111,14 @@ def test_create_archive_multiple_resource_types(self, mocker):
         self.assertTrue(get_uri(args).endswith('/auto/generate_archive'))
         self.assertEqual(test_ids, get_list_param(mocker, 'fully_qualified_public_ids'))
 
+    @unittest.skipUnless(cloudinary.config().api_secret, "requires api_key/api_secret")
+    def test_download_backedup_asset(self):
+        download_backedup_asset_url = utils.download_backedup_asset('b71b23d9c89a81a254b88a91a9dad8cd',
+                                                                    '0e493356d8a40b856c4863c026891a4e')
+
+        self.assertIn("asset_id", download_backedup_asset_url)
+        self.assertIn("version_id", download_backedup_asset_url)
+
 
 if __name__ == '__main__':
     unittest.main()