Prefer optional parameters to a dictionary containing the parameters

Author: OndraFiedler

README.rst

@@ -60,7 +60,7 @@ Basic example
 
         # Get recommendations for user 'user-25'
         print('Recommend for a user')
-        recommended = client.send(UserBasedRecommendation('user-25', 5, {'rotationRate': 0}))
+        recommended = client.send(UserBasedRecommendation('user-25', 5))
         print("Recommended items: %s" % recommended)
     except APIException as e:
         print(e)
@@ -121,27 +121,26 @@ Using property values
     for item_id in items:
         #Use cascadeCreate to create unexisting users
         purchasing_users = [user_id for user_id in users if random.random() < PROBABILITY_PURCHASED]
-        requests += [AddPurchase(user_id, item_id, {'cascadeCreate': True}) for user_id in purchasing_users]
+        requests += [AddPurchase(user_id, item_id, cascade_create=True) for user_id in purchasing_users]
 
     # Send purchases to the recommender system
     client.send(Batch(requests))
 
     # Get 5 recommendations for user-42, who is currently viewing computer-6
-    recommended = client.send(ItemBasedRecommendation('computer-6', 5, {'targetUserId': 'user-42'}) )
+    recommended = client.send(ItemBasedRecommendation('computer-6', 5, target_user_id='user-42'))
     print("Recommended items: %s" % recommended)
 
     # Get 5 recommendations for user-42, but recommend only computers that
     # have at least 3 cores
     recommended = client.send(
-        ItemBasedRecommendation('computer-6', 5, {'targetUserId': 'user-42', 'filter': "'num-cores'>=3"})
+        ItemBasedRecommendation('computer-6', 5, target_user_id='user-42', filter="'num-cores'>=3")
     )
     print("Recommended items with at least 3 processor cores: %s" % recommended)
 
     # Get 5 recommendations for user-42, but recommend only items that
     # are more expensive then currently viewed item (up-sell)
     recommended = client.send(
-        ItemBasedRecommendation('computer-6', 5,
-          {'targetUserId': 'user-42', 'filter': "'price' > context_item[\"price\"]"})
+        ItemBasedRecommendation('computer-6', 5, target_user_id='user-42', filter="'price' > context_item[\"price\"]")
     )
     print("Recommended up-sell items: %s" % recommended)
   
@@ -159,8 +158,7 @@ Example:
 
   try:
     recommended = client.send(
-    ItemBasedRecommendation('computer-6', 5,
-      {'targetUserId': 'user-42', 'filter': "'price' > context_item[\"price\"]"})
+    ItemBasedRecommendation('computer-6', 5,target_user_id='user-42', filter="'price' > context_item[\"price\"]")
     )
   except ResponseException as e:
     #Handle errorneous request => use fallback

recombee_api_client/api_requests/add_bookmark.py

@@ -6,27 +6,24 @@ class AddBookmark(Request):
 
     """
 
-    def __init__(self,user_id, item_id, optional = dict()):
+    def __init__(self,user_id, item_id, timestamp=None, cascade_create=None):
         """
         Required parameters:
         @param user_id: User who bookmarked the item
         
         @param item_id: Bookmarked item
         
         
-        Optional parameters (given as dictionary C{optional}):
+        Optional parameters:
         @param timestamp: UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
         
-        @param cascadeCreate: Sets whether the given user/item should be created if not present in the database.
+        @param cascade_create: Sets whether the given user/item should be created if not present in the database.
         
         """
         self.user_id = user_id
         self.item_id = item_id
-        self.timestamp = optional.get('timestamp')
-        self.cascade_create = optional.get('cascadeCreate')
-        for par in optional:
-            if not par in {"timestamp","cascadeCreate"}:
-                raise ValueError("Unknown parameter %s was given to the request" % par)
+        self.timestamp = timestamp
+        self.cascade_create = cascade_create
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'

recombee_api_client/api_requests/add_cart_addition.py

@@ -6,27 +6,24 @@ class AddCartAddition(Request):
 
     """
 
-    def __init__(self,user_id, item_id, optional = dict()):
+    def __init__(self,user_id, item_id, timestamp=None, cascade_create=None):
         """
         Required parameters:
         @param user_id: User who added the item to the cart
         
         @param item_id: Item added to the cart
         
         
-        Optional parameters (given as dictionary C{optional}):
+        Optional parameters:
         @param timestamp: UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
         
-        @param cascadeCreate: Sets whether the given user/item should be created if not present in the database.
+        @param cascade_create: Sets whether the given user/item should be created if not present in the database.
         
         """
         self.user_id = user_id
         self.item_id = item_id
-        self.timestamp = optional.get('timestamp')
-        self.cascade_create = optional.get('cascadeCreate')
-        for par in optional:
-            if not par in {"timestamp","cascadeCreate"}:
-                raise ValueError("Unknown parameter %s was given to the request" % par)
+        self.timestamp = timestamp
+        self.cascade_create = cascade_create
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'

recombee_api_client/api_requests/add_detail_view.py

@@ -6,30 +6,27 @@ class AddDetailView(Request):
 
     """
 
-    def __init__(self,user_id, item_id, optional = dict()):
+    def __init__(self,user_id, item_id, timestamp=None, duration=None, cascade_create=None):
         """
         Required parameters:
         @param user_id: User who viewed the item
         
         @param item_id: Viewed item
         
         
-        Optional parameters (given as dictionary C{optional}):
+        Optional parameters:
         @param timestamp: UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
         
         @param duration: Duration of the view
         
-        @param cascadeCreate: Sets whether the given user/item should be created if not present in the database.
+        @param cascade_create: Sets whether the given user/item should be created if not present in the database.
         
         """
         self.user_id = user_id
         self.item_id = item_id
-        self.timestamp = optional.get('timestamp')
-        self.duration = optional.get('duration')
-        self.cascade_create = optional.get('cascadeCreate')
-        for par in optional:
-            if not par in {"timestamp","duration","cascadeCreate"}:
-                raise ValueError("Unknown parameter %s was given to the request" % par)
+        self.timestamp = timestamp
+        self.duration = duration
+        self.cascade_create = cascade_create
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'

recombee_api_client/api_requests/add_purchase.py

@@ -6,27 +6,24 @@ class AddPurchase(Request):
 
     """
 
-    def __init__(self,user_id, item_id, optional = dict()):
+    def __init__(self,user_id, item_id, timestamp=None, cascade_create=None):
         """
         Required parameters:
         @param user_id: User who purchased the item
         
         @param item_id: Purchased item
         
         
-        Optional parameters (given as dictionary C{optional}):
+        Optional parameters:
         @param timestamp: UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
         
-        @param cascadeCreate: Sets whether the given user/item should be created if not present in the database.
+        @param cascade_create: Sets whether the given user/item should be created if not present in the database.
         
         """
         self.user_id = user_id
         self.item_id = item_id
-        self.timestamp = optional.get('timestamp')
-        self.cascade_create = optional.get('cascadeCreate')
-        for par in optional:
-            if not par in {"timestamp","cascadeCreate"}:
-                raise ValueError("Unknown parameter %s was given to the request" % par)
+        self.timestamp = timestamp
+        self.cascade_create = cascade_create
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'

recombee_api_client/api_requests/add_rating.py

@@ -6,7 +6,7 @@ class AddRating(Request):
 
     """
 
-    def __init__(self,user_id, item_id, rating, optional = dict()):
+    def __init__(self,user_id, item_id, rating, timestamp=None, cascade_create=None):
         """
         Required parameters:
         @param user_id: User who submitted the rating
@@ -16,20 +16,17 @@ def __init__(self,user_id, item_id, rating, optional = dict()):
         @param rating: Rating rescaled to interval [-1.0,1.0], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion.
         
         
-        Optional parameters (given as dictionary C{optional}):
+        Optional parameters:
         @param timestamp: UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
         
-        @param cascadeCreate: Sets whether the given user/item should be created if not present in the database.
+        @param cascade_create: Sets whether the given user/item should be created if not present in the database.
         
         """
         self.user_id = user_id
         self.item_id = item_id
         self.rating = rating
-        self.timestamp = optional.get('timestamp')
-        self.cascade_create = optional.get('cascadeCreate')
-        for par in optional:
-            if not par in {"timestamp","cascadeCreate"}:
-                raise ValueError("Unknown parameter %s was given to the request" % par)
+        self.timestamp = timestamp
+        self.cascade_create = cascade_create
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'post'

recombee_api_client/api_requests/batch.py

@@ -6,13 +6,13 @@ class Batch(Request):
     """
     Batch request for submitting an arbitrary sequence of requests
 
-     In many cases, it may be desirable to execute multiple requests at once. By example, when synchronizing the catalog of items in periodical manner, you would have to execute a sequence of thousands of separate POST requests, which is very ineffective and may take a very long time to complete. Most notably, network latencies can make execution of such a sequence very slow and even if executed in multiple parallel threads, there will still be unreasonable overhead caused by the HTTP(s). To avoid the problems mentioned, batch processing may be used, encapsulating a sequence of requests into a single HTTP request.
-     Batch processing allows you to submit arbitrary sequence of requests in form of JSON array. Any type of request from the above documentation may be used in the batch, and the batch may combine different types of requests arbitrarily as well.
-     Note that:
-     - executing the requests in a batch is equivalent as if they were executed one-by-one individually; there are, however, many optimizations to make batch execution as fast as possible,
-     - the status code of the batch request itself is 200 even if the individual requests result in error - you have to inspect the code values in the resulting array,
-     - if the status code of the whole batch is not 200, then there is an error in the batch request itself; in such a case, the error message returned should help you to resolve the problem,
-     - currently, batch size is limited to **10,000** requests; if you wish to execute even larger number of requests, please split the batch into multiple parts.
+    In many cases, it may be desirable to execute multiple requests at once. By example, when synchronizing the catalog of items in periodical manner, you would have to execute a sequence of thousands of separate POST requests, which is very ineffective and may take a very long time to complete. Most notably, network latencies can make execution of such a sequence very slow and even if executed in multiple parallel threads, there will still be unreasonable overhead caused by the HTTP(s). To avoid the problems mentioned, batch processing may be used, encapsulating a sequence of requests into a single HTTP request.
+    Batch processing allows you to submit arbitrary sequence of requests in form of JSON array. Any type of request from the above documentation may be used in the batch, and the batch may combine different types of requests arbitrarily as well.
+    Note that:
+    - executing the requests in a batch is equivalent as if they were executed one-by-one individually; there are, however, many optimizations to make batch execution as fast as possible,
+    - the status code of the batch request itself is 200 even if the individual requests result in error - you have to inspect the code values in the resulting array,
+    - if the status code of the whole batch is not 200, then there is an error in the batch request itself; in such a case, the error message returned should help you to resolve the problem,
+    - currently, batch size is limited to **10,000** requests; if you wish to execute even larger number of requests, please split the batch into multiple parts.
     """
 
     def __init__(self,requests):

recombee_api_client/api_requests/delete_bookmark.py

@@ -6,24 +6,21 @@ class DeleteBookmark(Request):
 
     """
 
-    def __init__(self,user_id, item_id, optional = dict()):
+    def __init__(self,user_id, item_id, timestamp=None):
         """
         Required parameters:
         @param user_id: ID of the user who made the bookmark.
         
         @param item_id: ID of the item of which was bookmarked.
         
         
-        Optional parameters (given as dictionary C{optional}):
+        Optional parameters:
         @param timestamp: Unix timestamp of the bookmark. If the `timestamp` is omitted, then all the bookmarks with given `userId` and `itemId` are deleted.
         
         """
         self.user_id = user_id
         self.item_id = item_id
-        self.timestamp = optional.get('timestamp')
-        for par in optional:
-            if not par in {"timestamp"}:
-                raise ValueError("Unknown parameter %s was given to the request" % par)
+        self.timestamp = timestamp
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'delete'

recombee_api_client/api_requests/delete_cart_addition.py

@@ -6,24 +6,21 @@ class DeleteCartAddition(Request):
 
     """
 
-    def __init__(self,user_id, item_id, optional = dict()):
+    def __init__(self,user_id, item_id, timestamp=None):
         """
         Required parameters:
         @param user_id: ID of the user who made the cart addition.
         
         @param item_id: ID of the item of which was added to cart.
         
         
-        Optional parameters (given as dictionary C{optional}):
+        Optional parameters:
         @param timestamp: Unix timestamp of the cart addition. If the `timestamp` is omitted, then all the cart additions with given `userId` and `itemId` are deleted.
         
         """
         self.user_id = user_id
         self.item_id = item_id
-        self.timestamp = optional.get('timestamp')
-        for par in optional:
-            if not par in {"timestamp"}:
-                raise ValueError("Unknown parameter %s was given to the request" % par)
+        self.timestamp = timestamp
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'delete'

recombee_api_client/api_requests/delete_detail_view.py

@@ -6,24 +6,21 @@ class DeleteDetailView(Request):
 
     """
 
-    def __init__(self,user_id, item_id, optional = dict()):
+    def __init__(self,user_id, item_id, timestamp=None):
         """
         Required parameters:
         @param user_id: ID of the user who made the detail view.
         
         @param item_id: ID of the item of which the details were viewed.
         
         
-        Optional parameters (given as dictionary C{optional}):
+        Optional parameters:
         @param timestamp: Unix timestamp of the detail view. If the `timestamp` is omitted, then all the detail views with given `userId` and `itemId` are deleted.
         
         """
         self.user_id = user_id
         self.item_id = item_id
-        self.timestamp = optional.get('timestamp')
-        for par in optional:
-            if not par in {"timestamp"}:
-                raise ValueError("Unknown parameter %s was given to the request" % par)
+        self.timestamp = timestamp
         self.timeout = 1000
         self.ensure_https = False
         self.method = 'delete'