Support returnProperties and includedProperties parameters of ListItems and ListUsers. Send User-Agent HTTP header. Use POST for recomm requests. Use artificial default value for parameters in order to allow sending null value.

Author: OndraFiedler

README.rst

@@ -2,7 +2,7 @@
 RecombeeApiClient
 *****************
 
-A Python client for easy use of the `Recombee <https://www.recombee.com/>`_  recommendation API.
+A Python client for easy use of the `Recombee <https://www.recombee.com/>`_  recommendation API. Both Python 2 and Python 3 are supported.
 
 If you don't have an account at Recombee yet, you can create a free account `here <https://www.recombee.com/>`_.
 
@@ -18,6 +18,8 @@ Install the client with pip:
 
     $ pip install recombee-api-client
 
+(use pip3 instead of pip if you use Python 3)
+
 ========
 Examples
 ========

recombee_api_client/api_client.py

@@ -61,25 +61,40 @@ def send(self, request):
         except requests.exceptions.Timeout:
             raise ApiTimeoutException(request)
 
+    @staticmethod
+    def __get_http_headers(additional_headers=None):
+        headers = {'User-Agent': 'recombee-python-api-client/1.4.0'}
+        if additional_headers:
+            headers.update(additional_headers)
+        return headers
+
     def __put(self, request, uri, timeout):
-        response = requests.put(uri, 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, uri, timeout):
-        response = requests.get(uri, 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, uri, timeout):
-        response = requests.post(uri, data=json.dumps(request.get_body_parameters()), 
-                                            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, uri, timeout):
-        response = requests.delete(uri, timeout=timeout)
+        response = requests.delete(uri,
+                                headers= self.__get_http_headers(),
+                                timeout=timeout)
         self.__check_errors(response, request)
         return response.json()
 
@@ -109,7 +124,6 @@ def __send_multipart_batch(self, batch):
 
     def __process_request_uri(self, request):
         uri = request.path
-        uri = uri[len('/{databaseId}/'):]
         uri += self.__query_parameters_to_url(request)
         return uri
 
@@ -131,7 +145,7 @@ def __format_query_parameter_value(self, value):
     # Sign request with HMAC, request URI must be exacly the same
     # We have 30s to complete request with this token
     def __sign_url(self, req_part):
-        uri = '/' + self.database_id + '/' + req_part
+        uri = '/' + self.database_id + req_part
         time = self.__hmac_time(uri)
         sign = self.__hmac_sign(uri, time)
         res = uri + time + '&hmac_sign=' +sign
@@ -145,4 +159,4 @@ def __hmac_time(self, uri):
     def __hmac_sign(self, uri, time):
         url = uri + time
         sign = hmac.new(str.encode(self.token), str.encode(url), sha1).hexdigest()
-        return sign
+        return sign

recombee_api_client/api_requests/add_bookmark.py

@@ -1,12 +1,15 @@
 from recombee_api_client.api_requests.request import Request
+import uuid
+
+DEFAULT = uuid.uuid4()
 
 class AddBookmark(Request):
     """
     Adds a bookmark of a given item made by a given user.
 
     """
 
-    def __init__(self,user_id, item_id, timestamp=None, cascade_create=None):
+    def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT):
         """
         Required parameters:
         @param user_id: User who bookmarked the item
@@ -27,7 +30,7 @@ def __init__(self,user_id, item_id, timestamp=None, cascade_create=None):
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'
-        self.path = "/{databaseId}/bookmarks/" % ()
+        self.path = "/bookmarks/" % ()
 
     def get_body_parameters(self):
         """
@@ -36,9 +39,9 @@ def get_body_parameters(self):
         p = dict()
         p['userId'] = self.user_id
         p['itemId'] = self.item_id
-        if self.timestamp is not None:
+        if self.timestamp is not DEFAULT:
             p['timestamp'] = self.timestamp
-        if self.cascade_create is not None:
+        if self.cascade_create is not DEFAULT:
             p['cascadeCreate'] = self.cascade_create
         return p
 

recombee_api_client/api_requests/add_cart_addition.py

@@ -1,12 +1,15 @@
 from recombee_api_client.api_requests.request import Request
+import uuid
+
+DEFAULT = uuid.uuid4()
 
 class AddCartAddition(Request):
     """
     Adds a cart addition of a given item made by a given user.
 
     """
 
-    def __init__(self,user_id, item_id, timestamp=None, cascade_create=None):
+    def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT):
         """
         Required parameters:
         @param user_id: User who added the item to the cart
@@ -27,7 +30,7 @@ def __init__(self,user_id, item_id, timestamp=None, cascade_create=None):
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'
-        self.path = "/{databaseId}/cartadditions/" % ()
+        self.path = "/cartadditions/" % ()
 
     def get_body_parameters(self):
         """
@@ -36,9 +39,9 @@ def get_body_parameters(self):
         p = dict()
         p['userId'] = self.user_id
         p['itemId'] = self.item_id
-        if self.timestamp is not None:
+        if self.timestamp is not DEFAULT:
             p['timestamp'] = self.timestamp
-        if self.cascade_create is not None:
+        if self.cascade_create is not DEFAULT:
             p['cascadeCreate'] = self.cascade_create
         return p
 

recombee_api_client/api_requests/add_detail_view.py

@@ -1,12 +1,15 @@
 from recombee_api_client.api_requests.request import Request
+import uuid
+
+DEFAULT = uuid.uuid4()
 
 class AddDetailView(Request):
     """
     Adds a detail view of a given item made by a given user.
 
     """
 
-    def __init__(self,user_id, item_id, timestamp=None, duration=None, cascade_create=None):
+    def __init__(self, user_id, item_id, timestamp=DEFAULT, duration=DEFAULT, cascade_create=DEFAULT):
         """
         Required parameters:
         @param user_id: User who viewed the item
@@ -30,7 +33,7 @@ def __init__(self,user_id, item_id, timestamp=None, duration=None, cascade_creat
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'
-        self.path = "/{databaseId}/detailviews/" % ()
+        self.path = "/detailviews/" % ()
 
     def get_body_parameters(self):
         """
@@ -39,11 +42,11 @@ def get_body_parameters(self):
         p = dict()
         p['userId'] = self.user_id
         p['itemId'] = self.item_id
-        if self.timestamp is not None:
+        if self.timestamp is not DEFAULT:
             p['timestamp'] = self.timestamp
-        if self.duration is not None:
+        if self.duration is not DEFAULT:
             p['duration'] = self.duration
-        if self.cascade_create is not None:
+        if self.cascade_create is not DEFAULT:
             p['cascadeCreate'] = self.cascade_create
         return p
 

recombee_api_client/api_requests/add_group.py

@@ -1,11 +1,14 @@
 from recombee_api_client.api_requests.request import Request
+import uuid
+
+DEFAULT = uuid.uuid4()
 
 class AddGroup(Request):
     """
     Creates new group in the database.
     """
 
-    def __init__(self,group_id):
+    def __init__(self, group_id):
         """
         Required parameters:
         @param group_id: ID of the group to be created.
@@ -15,7 +18,7 @@ def __init__(self,group_id):
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'put'
-        self.path = "/{databaseId}/groups/%s" % (self.group_id)
+        self.path = "/groups/%s" % (self.group_id)
 
     def get_body_parameters(self):
         """

recombee_api_client/api_requests/add_item.py

@@ -1,4 +1,7 @@
 from recombee_api_client.api_requests.request import Request
+import uuid
+
+DEFAULT = uuid.uuid4()
 
 class AddItem(Request):
     """
@@ -8,7 +11,7 @@ class AddItem(Request):
 
     """
 
-    def __init__(self,item_id):
+    def __init__(self, item_id):
         """
         Required parameters:
         @param item_id: ID of the item to be created.
@@ -18,7 +21,7 @@ def __init__(self,item_id):
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'put'
-        self.path = "/{databaseId}/items/%s" % (self.item_id)
+        self.path = "/items/%s" % (self.item_id)
 
     def get_body_parameters(self):
         """

recombee_api_client/api_requests/add_item_property.py

@@ -1,12 +1,15 @@
 from recombee_api_client.api_requests.request import Request
+import uuid
+
+DEFAULT = uuid.uuid4()
 
 class AddItemProperty(Request):
     """
     Adding an item property is somehow equivalent to adding a column to the table of items. The items may be characterized by various properties of different types.
 
     """
 
-    def __init__(self,property_name, type):
+    def __init__(self, property_name, type):
         """
         Required parameters:
         @param property_name: Name of the item property to be created. Currently, the following names are reserved:`id`, `itemid`, case insensitively. Also, the length of the property name must not exceed 63 characters.
@@ -21,7 +24,7 @@ def __init__(self,property_name, type):
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'put'
-        self.path = "/{databaseId}/items/properties/%s" % (self.property_name)
+        self.path = "/items/properties/%s" % (self.property_name)
 
     def get_body_parameters(self):
         """

recombee_api_client/api_requests/add_purchase.py

@@ -1,12 +1,15 @@
 from recombee_api_client.api_requests.request import Request
+import uuid
+
+DEFAULT = uuid.uuid4()
 
 class AddPurchase(Request):
     """
     Adds a purchase of a given item made by a given user.
 
     """
 
-    def __init__(self,user_id, item_id, timestamp=None, cascade_create=None):
+    def __init__(self, user_id, item_id, timestamp=DEFAULT, cascade_create=DEFAULT):
         """
         Required parameters:
         @param user_id: User who purchased the item
@@ -27,7 +30,7 @@ def __init__(self,user_id, item_id, timestamp=None, cascade_create=None):
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'
-        self.path = "/{databaseId}/purchases/" % ()
+        self.path = "/purchases/" % ()
 
     def get_body_parameters(self):
         """
@@ -36,9 +39,9 @@ def get_body_parameters(self):
         p = dict()
         p['userId'] = self.user_id
         p['itemId'] = self.item_id
-        if self.timestamp is not None:
+        if self.timestamp is not DEFAULT:
             p['timestamp'] = self.timestamp
-        if self.cascade_create is not None:
+        if self.cascade_create is not DEFAULT:
             p['cascadeCreate'] = self.cascade_create
         return p
 

recombee_api_client/api_requests/add_rating.py

@@ -1,12 +1,15 @@
 from recombee_api_client.api_requests.request import Request
+import uuid
+
+DEFAULT = uuid.uuid4()
 
 class AddRating(Request):
     """
     Adds a rating of given item made by a given user.
 
     """
 
-    def __init__(self,user_id, item_id, rating, timestamp=None, cascade_create=None):
+    def __init__(self, user_id, item_id, rating, timestamp=DEFAULT, cascade_create=DEFAULT):
         """
         Required parameters:
         @param user_id: User who submitted the rating
@@ -30,7 +33,7 @@ def __init__(self,user_id, item_id, rating, timestamp=None, cascade_create=None)
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'
-        self.path = "/{databaseId}/ratings/" % ()
+        self.path = "/ratings/" % ()
 
     def get_body_parameters(self):
         """
@@ -40,9 +43,9 @@ def get_body_parameters(self):
         p['userId'] = self.user_id
         p['itemId'] = self.item_id
         p['rating'] = self.rating
-        if self.timestamp is not None:
+        if self.timestamp is not DEFAULT:
             p['timestamp'] = self.timestamp
-        if self.cascade_create is not None:
+        if self.cascade_create is not DEFAULT:
             p['cascadeCreate'] = self.cascade_create
         return p