Release: v6.0.0

- Added support for the new Composite Recommendation endpoint
- Added new parameter `autoPresented` for Detail View and View Portion interactions
- Added new parameter `timeSpent` for View Portion interactions
- Added support for `reqlExpressions` on recommended items
- Added support for input classes
- Format code using `black`

Author: OndraFiedler

recombee_api_client/api_client.py

@@ -17,6 +17,7 @@ class Region(Enum):
     """
     Region of the Recombee cluster
     """
+
     AP_SE = 1
     CA_EAST = 2
     EU_WEST = 3
@@ -28,16 +29,24 @@ class RecombeeClient:
     Client for sending requests to Recombee recommender system
 
     :param database_id: Name of your database_id at Recombee
-    
+
     :param token: Secret token obtained from Recombee for signing requests
-    
+
     :param protocol: Default protocol for sending requests. Possible values: 'http', 'https'.
 
     :param region: region of the Recombee cluster where the database is located
     """
+
     BATCH_MAX_SIZE = 10000
 
-    def __init__(self, database_id: str, token: str, protocol: str = 'https', options: dict = None, region: Region = None):
+    def __init__(
+        self,
+        database_id: str,
+        token: str,
+        protocol: str = "https",
+        options: dict = None,
+        region: Region = None,
+    ):
         self.database_id = database_id
         self.token = token
         self.protocol = protocol
@@ -48,85 +57,91 @@ def send(self, request: Request) -> Union[dict, str, list]:
         """
         :param request: Request to be sent to Recombee recommender
         """
-        
+
         if isinstance(request, Batch) and len(request.requests) > self.BATCH_MAX_SIZE:
             return self.__send_multipart_batch(request)
 
         timeout = request.timeout / 1000
         uri = self.__process_request_uri(request)
         uri = self.__sign_url(uri)
-        protocol = 'https' if request.ensure_https else self.protocol
-        uri = protocol + '://' + self.base_uri + uri
+        protocol = "https" if request.ensure_https else self.protocol
+        uri = protocol + "://" + self.base_uri + uri
         try:
-            if request.method == 'put':
+            if request.method == "put":
                 return self.__put(request, uri, timeout)
-            elif request.method == 'get':
+            elif request.method == "get":
                 return self.__get(request, uri, timeout)
-            elif request.method == 'post':
+            elif request.method == "post":
                 return self.__post(request, uri, timeout)
-            elif request.method == 'delete':
+            elif request.method == "delete":
                 return self.__delete(request, uri, timeout)
         except requests.exceptions.Timeout:
             raise ApiTimeoutException(request)
 
     @staticmethod
     def __get_regional_base_uri(region: Region) -> str:
         uri = {
-            Region.AP_SE: 'rapi-ap-se.recombee.com',
-            Region.CA_EAST: 'rapi-ca-east.recombee.com',
-            Region.EU_WEST: 'rapi-eu-west.recombee.com',
-            Region.US_WEST: 'rapi-us-west.recombee.com'
-          }.get(region)
+            Region.AP_SE: "rapi-ap-se.recombee.com",
+            Region.CA_EAST: "rapi-ca-east.recombee.com",
+            Region.EU_WEST: "rapi-eu-west.recombee.com",
+            Region.US_WEST: "rapi-us-west.recombee.com",
+        }.get(region)
 
         if uri is None:
-            raise ValueError('Unknown region given')
+            raise ValueError("Unknown region given")
         return uri
 
     @staticmethod
     def __get_base_uri(options: dict, region: str) -> str:
-        base_uri = os.environ.get('RAPI_URI') or options.get('base_uri')
+        base_uri = os.environ.get("RAPI_URI") or options.get("base_uri")
         if region is not None:
             if base_uri:
-                raise ValueError('base_uri and region cannot be specified at the same time')
+                raise ValueError(
+                    "base_uri and region cannot be specified at the same time"
+                )
             base_uri = RecombeeClient.__get_regional_base_uri(region)
 
-        return base_uri or 'rapi.recombee.com'
+        return base_uri or "rapi.recombee.com"
 
     @staticmethod
     def __get_http_headers(additional_headers: dict = None) -> dict:
-        headers = {'User-Agent': 'recombee-python-api-client/5.1.0'}
+        headers = {"User-Agent": "recombee-python-api-client/6.0.0"}
         if additional_headers:
             headers.update(additional_headers)
         return headers
 
     def __put(self, request: Request, uri: str, timeout: int):
-        response = requests.put(uri, 
-                                data=json.dumps(request.get_body_parameters()),
-                                headers=self.__get_http_headers({'Content-Type': 'application/json'}),
-                                timeout=timeout)
+        response = requests.put(
+            uri,
+            data=json.dumps(request.get_body_parameters()),
+            headers=self.__get_http_headers({"Content-Type": "application/json"}),
+            timeout=timeout,
+        )
         self.__check_errors(response, request)
         return response.json()
 
     def __get(self, request: Request, uri: str, timeout: int):
-        response = requests.get(uri,
-                                headers=self.__get_http_headers(),
-                                timeout=timeout)
+        response = requests.get(uri, headers=self.__get_http_headers(), timeout=timeout)
         self.__check_errors(response, request)
         return response.json()
 
     def __post(self, request: Request, uri: str, timeout: int):
-        response = requests.post(uri,
-                                 data=json.dumps(request.get_body_parameters()),
-                                 headers=self.__get_http_headers({'Content-Type': 'application/json'}),
-                                 timeout=timeout)
+        response = requests.post(
+            uri,
+            data=json.dumps(request.get_body_parameters()),
+            headers=self.__get_http_headers({"Content-Type": "application/json"}),
+            timeout=timeout,
+        )
         self.__check_errors(response, request)
         return response.json()
 
     def __delete(self, request: Request, uri: str, timeout: int):
-        response = requests.delete(uri,
-                                   data=json.dumps(request.get_body_parameters()),
-                                   headers=self.__get_http_headers({'Content-Type': 'application/json'}),
-                                   timeout=timeout)
+        response = requests.delete(
+            uri,
+            data=json.dumps(request.get_body_parameters()),
+            headers=self.__get_http_headers({"Content-Type": "application/json"}),
+            timeout=timeout,
+        )
         self.__check_errors(response, request)
         return response.json()
 
@@ -141,10 +156,12 @@ def __get_list_chunks(l: list, n: int) -> list:
         """Yield successive n-sized chunks from l."""
 
         for i in range(0, len(l), n):
-            yield l[i:i + n]
+            yield l[i : i + n]
 
     def __send_multipart_batch(self, batch: Batch) -> list:
-        requests_parts = [rqs for rqs in self.__get_list_chunks(batch.requests, self.BATCH_MAX_SIZE)]
+        requests_parts = [
+            rqs for rqs in self.__get_list_chunks(batch.requests, self.BATCH_MAX_SIZE)
+        ]
         responses = [self.send(Batch(rqs)) for rqs in requests_parts]
         return sum(responses, [])
 
@@ -154,31 +171,31 @@ def __process_request_uri(self, request: Request) -> str:
         return uri
 
     def __query_parameters_to_url(self, request: Request) -> str:
-        ps = ''
+        ps = ""
         query_params = request.get_query_parameters()
         for name in query_params:
             val = query_params[name]
-            ps += '&' if ps.find('?') != -1 else '?'
+            ps += "&" if ps.find("?") != -1 else "?"
             ps += "%s=%s" % (name, self.__format_query_parameter_value(val))
         return ps
 
     @staticmethod
     def __format_query_parameter_value(value) -> str:
         if isinstance(value, list):
-            return ','.join([quote(str(v)) for v in value])
+            return ",".join([quote(str(v)) for v in value])
         return quote(str(value))
 
     # Sign request with HMAC, request URI must be exactly the same
     # We have 30s to complete request with this token
     def __sign_url(self, req_part: str) -> str:
-        uri = '/' + self.database_id + req_part
+        uri = "/" + self.database_id + req_part
         time_part = self.__hmac_time(uri)
         sign = self.__hmac_sign(uri, time_part)
-        res = uri + time_part + '&hmac_sign=' + sign
+        res = uri + time_part + "&hmac_sign=" + sign
         return res
 
     def __hmac_time(self, uri: str) -> str:
-        res = '&' if uri.find('?') != -1 else '?'
+        res = "&" if uri.find("?") != -1 else "?"
         res += "hmac_timestamp=%s" % int(time.time())
         return res
 

recombee_api_client/api_requests/__init__.py

@@ -39,40 +39,87 @@
 from recombee_api_client.api_requests.list_user_ratings import ListUserRatings
 from recombee_api_client.api_requests.add_cart_addition import AddCartAddition
 from recombee_api_client.api_requests.delete_cart_addition import DeleteCartAddition
-from recombee_api_client.api_requests.list_item_cart_additions import ListItemCartAdditions
-from recombee_api_client.api_requests.list_user_cart_additions import ListUserCartAdditions
+from recombee_api_client.api_requests.list_item_cart_additions import (
+    ListItemCartAdditions,
+)
+from recombee_api_client.api_requests.list_user_cart_additions import (
+    ListUserCartAdditions,
+)
 from recombee_api_client.api_requests.add_bookmark import AddBookmark
 from recombee_api_client.api_requests.delete_bookmark import DeleteBookmark
 from recombee_api_client.api_requests.list_item_bookmarks import ListItemBookmarks
 from recombee_api_client.api_requests.list_user_bookmarks import ListUserBookmarks
 from recombee_api_client.api_requests.set_view_portion import SetViewPortion
 from recombee_api_client.api_requests.delete_view_portion import DeleteViewPortion
-from recombee_api_client.api_requests.list_item_view_portions import ListItemViewPortions
-from recombee_api_client.api_requests.list_user_view_portions import ListUserViewPortions
-from recombee_api_client.api_requests.recommend_items_to_user import RecommendItemsToUser
-from recombee_api_client.api_requests.recommend_items_to_item import RecommendItemsToItem
-from recombee_api_client.api_requests.recommend_items_to_item_segment import RecommendItemsToItemSegment
+from recombee_api_client.api_requests.list_item_view_portions import (
+    ListItemViewPortions,
+)
+from recombee_api_client.api_requests.list_user_view_portions import (
+    ListUserViewPortions,
+)
+from recombee_api_client.api_requests.recommend_items_to_user import (
+    RecommendItemsToUser,
+)
+from recombee_api_client.api_requests.recommend_items_to_item import (
+    RecommendItemsToItem,
+)
+from recombee_api_client.api_requests.recommend_items_to_item_segment import (
+    RecommendItemsToItemSegment,
+)
 from recombee_api_client.api_requests.recommend_next_items import RecommendNextItems
-from recombee_api_client.api_requests.recommend_users_to_user import RecommendUsersToUser
-from recombee_api_client.api_requests.recommend_users_to_item import RecommendUsersToItem
-from recombee_api_client.api_requests.recommend_item_segments_to_user import RecommendItemSegmentsToUser
-from recombee_api_client.api_requests.recommend_item_segments_to_item import RecommendItemSegmentsToItem
-from recombee_api_client.api_requests.recommend_item_segments_to_item_segment import RecommendItemSegmentsToItemSegment
+from recombee_api_client.api_requests.recommend_users_to_user import (
+    RecommendUsersToUser,
+)
+from recombee_api_client.api_requests.recommend_users_to_item import (
+    RecommendUsersToItem,
+)
+from recombee_api_client.api_requests.recommend_item_segments_to_user import (
+    RecommendItemSegmentsToUser,
+)
+from recombee_api_client.api_requests.recommend_item_segments_to_item import (
+    RecommendItemSegmentsToItem,
+)
+from recombee_api_client.api_requests.recommend_item_segments_to_item_segment import (
+    RecommendItemSegmentsToItemSegment,
+)
+from recombee_api_client.api_requests.composite_recommendation import (
+    CompositeRecommendation,
+)
 from recombee_api_client.api_requests.search_items import SearchItems
 from recombee_api_client.api_requests.search_item_segments import SearchItemSegments
 from recombee_api_client.api_requests.add_search_synonym import AddSearchSynonym
 from recombee_api_client.api_requests.list_search_synonyms import ListSearchSynonyms
-from recombee_api_client.api_requests.delete_all_search_synonyms import DeleteAllSearchSynonyms
+from recombee_api_client.api_requests.delete_all_search_synonyms import (
+    DeleteAllSearchSynonyms,
+)
 from recombee_api_client.api_requests.delete_search_synonym import DeleteSearchSynonym
-from recombee_api_client.api_requests.create_property_based_segmentation import CreatePropertyBasedSegmentation
-from recombee_api_client.api_requests.update_property_based_segmentation import UpdatePropertyBasedSegmentation
-from recombee_api_client.api_requests.create_auto_reql_segmentation import CreateAutoReqlSegmentation
-from recombee_api_client.api_requests.update_auto_reql_segmentation import UpdateAutoReqlSegmentation
-from recombee_api_client.api_requests.create_manual_reql_segmentation import CreateManualReqlSegmentation
-from recombee_api_client.api_requests.update_manual_reql_segmentation import UpdateManualReqlSegmentation
-from recombee_api_client.api_requests.add_manual_reql_segment import AddManualReqlSegment
-from recombee_api_client.api_requests.update_manual_reql_segment import UpdateManualReqlSegment
-from recombee_api_client.api_requests.delete_manual_reql_segment import DeleteManualReqlSegment
+from recombee_api_client.api_requests.create_property_based_segmentation import (
+    CreatePropertyBasedSegmentation,
+)
+from recombee_api_client.api_requests.update_property_based_segmentation import (
+    UpdatePropertyBasedSegmentation,
+)
+from recombee_api_client.api_requests.create_auto_reql_segmentation import (
+    CreateAutoReqlSegmentation,
+)
+from recombee_api_client.api_requests.update_auto_reql_segmentation import (
+    UpdateAutoReqlSegmentation,
+)
+from recombee_api_client.api_requests.create_manual_reql_segmentation import (
+    CreateManualReqlSegmentation,
+)
+from recombee_api_client.api_requests.update_manual_reql_segmentation import (
+    UpdateManualReqlSegmentation,
+)
+from recombee_api_client.api_requests.add_manual_reql_segment import (
+    AddManualReqlSegment,
+)
+from recombee_api_client.api_requests.update_manual_reql_segment import (
+    UpdateManualReqlSegment,
+)
+from recombee_api_client.api_requests.delete_manual_reql_segment import (
+    DeleteManualReqlSegment,
+)
 from recombee_api_client.api_requests.list_segmentations import ListSegmentations
 from recombee_api_client.api_requests.get_segmentation import GetSegmentation
 from recombee_api_client.api_requests.delete_segmentation import DeleteSegmentation