Introduce bucketing ID in Python SDK (#92)

Author: aliabbasrizvi

optimizely/bucketer.py

@@ -23,7 +23,7 @@
 UNSIGNED_MAX_32_BIT_VALUE = 0xFFFFFFFF
 MAX_HASH_VALUE = math.pow(2, 32)
 HASH_SEED = 1
-BUCKETING_ID_TEMPLATE = '{user_id}{parent_id}'
+BUCKETING_ID_TEMPLATE = '{bucketing_id}{parent_id}'
 GROUP_POLICIES = ['random']
 
 
@@ -66,21 +66,23 @@ def _generate_bucket_value(self, bucketing_id):
     ratio = float(self._generate_unsigned_hash_code_32_bit(bucketing_id)) / MAX_HASH_VALUE
     return math.floor(ratio * MAX_TRAFFIC_VALUE)
 
-  def find_bucket(self, user_id, parent_id, traffic_allocations):
+  def find_bucket(self, bucketing_id, parent_id, traffic_allocations):
     """ Determine entity based on bucket value and traffic allocations.
 
     Args:
-      user_id: ID for user.
+      bucketing_id: ID to be used for bucketing the user.
       parent_id: ID representing group or experiment.
       traffic_allocations: Traffic allocations representing traffic allotted to experiments or variations.
 
     Returns:
       Entity ID which may represent experiment or variation.
     """
 
-    bucketing_id = BUCKETING_ID_TEMPLATE.format(user_id=user_id, parent_id=parent_id)
-    bucketing_number = self._generate_bucket_value(bucketing_id)
-    self.config.logger.log(enums.LogLevels.DEBUG, 'Assigned bucket %s to user "%s".' % (bucketing_number, user_id))
+    bucketing_key = BUCKETING_ID_TEMPLATE.format(bucketing_id=bucketing_id, parent_id=parent_id)
+    bucketing_number = self._generate_bucket_value(bucketing_key)
+    self.config.logger.log(enums.LogLevels.DEBUG,
+                           'Assigned bucket %s to user with bucketing ID "%s".' % (bucketing_number,
+                                                                                   bucketing_id))
 
     for traffic_allocation in traffic_allocations:
       current_end_of_range = traffic_allocation.get('endOfRange')
@@ -89,12 +91,13 @@ def find_bucket(self, user_id, parent_id, traffic_allocations):
 
     return None
 
-  def bucket(self, experiment, user_id):
+  def bucket(self, experiment, user_id, bucketing_id):
     """ For a given experiment and bucketing ID determines variation to be shown to user.
 
     Args:
       experiment: Object representing the experiment for which user is to be bucketed.
       user_id: ID for user.
+      bucketing_id: ID to be used for bucketing the user.
 
     Returns:
       Variation in which user with ID user_id will be put in. None if no variation.
@@ -110,7 +113,7 @@ def bucket(self, experiment, user_id):
       if not group:
         return None
 
-      user_experiment_id = self.find_bucket(user_id, experiment.groupId, group.trafficAllocation)
+      user_experiment_id = self.find_bucket(bucketing_id, experiment.groupId, group.trafficAllocation)
       if not user_experiment_id:
         self.config.logger.log(enums.LogLevels.INFO, 'User "%s" is in no experiment.' % user_id)
         return None
@@ -124,7 +127,7 @@ def bucket(self, experiment, user_id):
                              (user_id, experiment.key, experiment.groupId))
 
     # Bucket user if not in white-list and in group (if any)
-    variation_id = self.find_bucket(user_id, experiment.id, experiment.trafficAllocation)
+    variation_id = self.find_bucket(bucketing_id, experiment.id, experiment.trafficAllocation)
     if variation_id:
       variation = self.config.get_variation_from_id(experiment.key, variation_id)
       self.config.logger.log(enums.LogLevels.INFO, 'User "%s" is in variation "%s" of experiment %s.' %

optimizely/decision_service.py

@@ -25,6 +25,7 @@
 Decision = namedtuple('Decision', 'experiment variation source')
 DECISION_SOURCE_EXPERIMENT = 'experiment'
 DECISION_SOURCE_ROLLOUT = 'rollout'
+RESERVED_BUCKETING_ID_ATTRIBUTE = '$opt_bucketing_id'
 
 
 class DecisionService(object):
@@ -36,6 +37,21 @@ def __init__(self, config, user_profile_service):
     self.config = config
     self.logger = config.logger
 
+  @staticmethod
+  def _get_bucketing_id(user_id, attributes):
+    """ Helper method to determine bucketing ID for the user.
+
+    Args:
+      user_id: ID for user.
+      attributes: Dict representing user attributes. May consist of bucketing ID to be used.
+
+    Returns:
+      String representing bucketing ID for the user. Fallback to user's ID if not provided.
+    """
+
+    attributes = attributes or {}
+    return attributes.get(RESERVED_BUCKETING_ID_ATTRIBUTE, user_id)
+
   def get_forced_variation(self, experiment, user_id):
     """ Determine if a user is forced into a variation for the given experiment and return that variation.
 
@@ -145,7 +161,9 @@ def get_variation(self, experiment, user_id, attributes, ignore_user_profile=Fal
       )
       return None
 
-    variation = self.bucketer.bucket(experiment, user_id)
+    # Determine bucketing ID to be used
+    bucketing_id = self._get_bucketing_id(user_id, attributes)
+    variation = self.bucketer.bucket(experiment, user_id, bucketing_id)
 
     if variation:
       # Store this new decision and return the variation for the user
@@ -188,7 +206,9 @@ def get_variation_for_rollout(self, rollout, user_id, attributes=None):
           continue
 
         self.logger.log(enums.LogLevels.DEBUG, 'User "%s" meets conditions for targeting rule %s.' % (user_id, idx + 1))
-        variation = self.bucketer.bucket(experiment, user_id)
+        # Determine bucketing ID to be used
+        bucketing_id = self._get_bucketing_id(user_id, attributes)
+        variation = self.bucketer.bucket(experiment, user_id, bucketing_id)
         if variation:
           self.logger.log(enums.LogLevels.DEBUG,
                           'User "%s" is in variation %s of experiment %s.' % (user_id, variation.key, experiment.key))
@@ -205,14 +225,42 @@ def get_variation_for_rollout(self, rollout, user_id, attributes=None):
       if audience_helper.is_user_in_experiment(self.config,
                                                self.config.get_experiment_from_key(rollout.experiments[-1].get('key')),
                                                attributes):
-        variation = self.bucketer.bucket(everyone_else_experiment, user_id)
+        # Determine bucketing ID to be used
+        bucketing_id = self._get_bucketing_id(user_id, attributes)
+        variation = self.bucketer.bucket(everyone_else_experiment, user_id, bucketing_id)
         if variation:
           self.logger.log(enums.LogLevels.DEBUG,
                           'User "%s" meets conditions for targeting rule "Everyone Else".' % user_id)
           return Decision(everyone_else_experiment, variation, DECISION_SOURCE_ROLLOUT)
 
     return Decision(None, None, DECISION_SOURCE_ROLLOUT)
 
+  def get_experiment_in_group(self, group, bucketing_id):
+    """ Determine which experiment in the group the user is bucketed into.
+
+    Args:
+      group: The group to bucket the user into.
+      bucketing_id: ID to be used for bucketing the user.
+
+    Returns:
+      Experiment if the user is bucketed into an experiment in the specified group. None otherwise.
+    """
+
+    experiment_id = self.bucketer.find_bucket(bucketing_id, group.id, group.trafficAllocation)
+    if experiment_id:
+      experiment = self.config.get_experiment_from_id(experiment_id)
+      if experiment:
+        self.logger.log(enums.LogLevels.INFO,
+                        'User with bucketing ID "%s" is in experiment %s of group %s.' %
+                        (bucketing_id, experiment.key, group.id))
+        return experiment
+
+    self.logger.log(enums.LogLevels.INFO,
+                    'User with bucketing ID "%s" is not in any experiments of group %s.' %
+                    (bucketing_id, group.id))
+
+    return None
+
   def get_variation_for_feature(self, feature, user_id, attributes=None):
     """ Returns the experiment/variation the user is bucketed in for the given feature.
 
@@ -227,12 +275,13 @@ def get_variation_for_feature(self, feature, user_id, attributes=None):
 
     experiment = None
     variation = None
+    bucketing_id = self._get_bucketing_id(user_id, attributes)
 
     # First check if the feature is in a mutex group
     if feature.groupId:
       group = self.config.get_group(feature.groupId)
       if group:
-        experiment = self.get_experiment_in_group(group, user_id)
+        experiment = self.get_experiment_in_group(group, bucketing_id)
         if experiment and experiment.id in feature.experimentIds:
           variation = self.get_variation(experiment, user_id, attributes)
 
@@ -259,29 +308,3 @@ def get_variation_for_feature(self, feature, user_id, attributes=None):
       return self.get_variation_for_rollout(rollout, user_id, attributes)
 
     return Decision(experiment, variation, DECISION_SOURCE_EXPERIMENT)
-
-  def get_experiment_in_group(self, group, user_id):
-    """ Determine which experiment in the group the user is bucketed into.
-
-    Args:
-      group: The group to bucket the user into.
-      user_id: ID of the user.
-
-    Returns:
-      Experiment if the user is bucketed into an experiment in the specified group. None otherwise.
-    """
-
-    experiment_id = self.bucketer.find_bucket(user_id, group.id, group.trafficAllocation)
-    if experiment_id:
-      experiment = self.config.get_experiment_from_id(experiment_id)
-      if experiment:
-        self.logger.log(enums.LogLevels.INFO,
-                        'User "%s" is in experiment %s of group %s.' %
-                        (user_id, experiment.key, group.id))
-        return experiment
-
-    self.logger.log(enums.LogLevels.INFO,
-                    'User "%s" is not in any experiments of group %s.' %
-                    (user_id, group.id))
-
-    return None