Merge pull request #55 from optimizely/devel

Merge devel into master

Author: mikeproeng37

CONTRIBUTING.md

@@ -1,15 +1,16 @@
 # Contributing to the Optimizely Python SDK
+
 We welcome contributions and feedback! All contributors must sign our [Contributor License Agreement (CLA)](https://docs.google.com/a/optimizely.com/forms/d/e/1FAIpQLSf9cbouWptIpMgukAKZZOIAhafvjFCV8hS00XJLWQnWDFtwtA/viewform) to be eligible to contribute. Please read the [README](README.md) to set up your development environment, then read the guidelines below for information on submitting your code.
 
 ## Development process
 
-1. Create a branch off of `devel`: `git checkout -b YOUR_NAME/branch_name`.
+1. Create a branch off of `master`: `git checkout -b YOUR_NAME/branch_name`.
 2. Commit your changes. Make sure to add tests!
-3. Lint your changes before submitting with `pep8 YOUR_CHANGED_FILES.py`.
+3. Lint your changes before submitting: `pep8 YOUR_CHANGED_FILES.py`.
 4. `git push` your changes to GitHub.
-5. Make sure that all unit tests are passing and that there are no merge conflicts between your branch and `devel`.
-6. Open a pull request from `YOUR_NAME/branch_name` to `devel`.
-7. A repository maintainer will review your pull request and, if all goes well, merge it!
+5. Make sure that all unit tests are passing and that there are no merge conflicts between your branch and `master`.
+6. Open a pull request from `YOUR_NAME/branch_name` to `master`.
+7. A repository maintainer will review your pull request and, if all goes well, squash and merge it!
 
 ## Pull request acceptance criteria
 
@@ -19,20 +20,22 @@ We welcome contributions and feedback! All contributors must sign our [Contribut
 * Lint your code with PEP-8 before submitting.
 
 ## Style
+
 We enforce PEP-8 rules with a few minor deviations.
 
 ## License
 
 All contributions are under the CLA mentioned above. For this project, Optimizely uses the Apache 2.0 license, and so asks that by contributing your code, you agree to license your contribution under the terms of the [Apache License v2.0](http://www.apache.org/licenses/LICENSE-2.0). Your contributions should also include the following header:
 
 ```
-# Copyright 2017, Optimizely
+# Copyright YEAR, Optimizely, Inc. and contributors
+#
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
 # http://www.apache.org/licenses/LICENSE-2.0
-
+#
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -43,4 +46,5 @@ All contributions are under the CLA mentioned above. For this project, Optimizel
 The YEAR above should be the year of the contribution. If work on the file has been done over multiple years, list each year in the section above. Example: Optimizely writes the file and releases it in 2014. No changes are made in 2015. Change made in 2016. YEAR should be “2014, 2016”.
 
 ## Contact
+
 If you have questions, please contact [email protected].

optimizely/bucketer.py

@@ -1,4 +1,4 @@
-# Copyright 2016, Optimizely
+# Copyright 2016-2017, Optimizely
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -103,16 +103,6 @@ def bucket(self, experiment, user_id):
     if not experiment:
       return None
 
-    # Check if user is white-listed for a variation
-    forced_variations = experiment.forcedVariations
-    if forced_variations and user_id in forced_variations:
-      variation_key = forced_variations.get(user_id)
-      variation = self.config.get_variation_from_key(experiment.key, variation_key)
-      if variation:
-        self.config.logger.log(enums.LogLevels.INFO,
-                               'User "%s" is forced in variation "%s".' % (user_id, variation_key))
-      return variation
-
     # Determine if experiment is in a mutually exclusive group
     if experiment.groupPolicy in GROUP_POLICIES:
       group = self.config.get_group(experiment.groupId)

optimizely/decision_service.py

@@ -0,0 +1,150 @@
+# Copyright 2017, Optimizely
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import sys
+
+from . import bucketer
+from .helpers import audience as audience_helper
+from .helpers import enums
+from .helpers import experiment as experiment_helper
+from .helpers import validator
+from .user_profile import UserProfile
+
+
+class DecisionService(object):
+  """ Class encapsulating all decision related capabilities. """
+
+  def __init__(self, config, user_profile_service):
+    self.bucketer = bucketer.Bucketer(config)
+    self.user_profile_service = user_profile_service
+    self.config = config
+    self.logger = config.logger
+
+  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.
+
+    Args:
+      experiment: Object representing the experiment for which user is to be bucketed.
+      user_id: ID for the user.
+
+    Returns:
+      Variation in which the user with ID user_id is forced into. None if no variation.
+    """
+
+    forced_variations = experiment.forcedVariations
+    if forced_variations and user_id in forced_variations:
+      variation_key = forced_variations.get(user_id)
+      variation = self.config.get_variation_from_key(experiment.key, variation_key)
+      if variation:
+        self.config.logger.log(enums.LogLevels.INFO,
+                               'User "%s" is forced in variation "%s".' % (user_id, variation_key))
+      return variation
+
+    return None
+
+  def get_stored_variation(self, experiment, user_profile):
+    """ Determine if the user has a stored variation available for the given experiment and return that.
+
+    Args:
+      experiment: Object representing the experiment for which user is to be bucketed.
+      user_profile: UserProfile object representing the user's profile.
+
+    Returns:
+      Variation if available. None otherwise.
+    """
+
+    user_id = user_profile.user_id
+    variation_id = user_profile.get_variation_for_experiment(experiment.id)
+
+    if variation_id:
+      variation = self.config.get_variation_from_id(experiment.key, variation_id)
+      if variation:
+        self.config.logger.log(enums.LogLevels.INFO,
+                               'Found a stored decision. User "%s" is in variation "%s" of experiment "%s".' %
+                               (user_id, variation.key, experiment.key))
+        return variation
+
+    return None
+
+  def get_variation(self, experiment, user_id, attributes):
+    """ Top-level function to help determine variation user should be put in.
+
+    First, check if experiment is running.
+    Second, check if user is forced in a variation.
+    Third, check if there is a stored decision for the user and return the corresponding variation.
+    Fourth, figure out if user is in the experiment by evaluating audience conditions if any.
+    Fifth, bucket the user and return the variation.
+
+    Args:
+      experiment_key: Experiment for which user variation needs to be determined.
+      user_id: ID for user.
+      attributes: Dict representing user attributes.
+
+    Returns:
+      Variation user should see. None if user is not in experiment or experiment is not running.
+    """
+
+    # Check if experiment is running
+    if not experiment_helper.is_experiment_running(experiment):
+      self.logger.log(enums.LogLevels.INFO, 'Experiment "%s" is not running.' % experiment.key)
+      return None
+
+    # Check to see if user is white-listed for a certain variation
+    variation = self.get_forced_variation(experiment, user_id)
+    if variation:
+      return variation
+
+    # Check to see if user has a decision available for the given experiment
+    user_profile = UserProfile(user_id)
+    if self.user_profile_service:
+      try:
+        retrieved_profile = self.user_profile_service.lookup(user_id)
+      except:
+        error = sys.exc_info()[1]
+        self.logger.log(
+          enums.LogLevels.ERROR,
+          'Unable to retrieve user profile for user "%s" as lookup failed. Error: %s' % (user_id, str(error))
+        )
+        retrieved_profile = None
+
+      if validator.is_user_profile_valid(retrieved_profile):
+        user_profile = UserProfile(**retrieved_profile)
+        variation = self.get_stored_variation(experiment, user_profile)
+        if variation:
+          return variation
+      else:
+        self.logger.log(enums.LogLevels.WARNING, 'User profile has invalid format.')
+
+    # Bucket user and store the new decision
+    if not audience_helper.is_user_in_experiment(self.config, experiment, attributes):
+      self.logger.log(
+        enums.LogLevels.INFO,
+        'User "%s" does not meet conditions to be in experiment "%s".' % (user_id, experiment.key)
+      )
+      return None
+
+    variation = self.bucketer.bucket(experiment, user_id)
+
+    if variation:
+      # Store this new decision and return the variation for the user
+      if self.user_profile_service:
+        try:
+          user_profile.save_variation_for_experiment(experiment.id, variation.id)
+          self.user_profile_service.save(user_profile.__dict__)
+        except:
+          error = sys.exc_info()[1]
+          self.logger.log(enums.LogLevels.ERROR,
+                          'Unable to save user profile for user "%s". Error: %s' % (user_id, str(error)))
+      return variation
+
+    return None

optimizely/entities.py

@@ -58,6 +58,22 @@ def __init__(self, id, key, status, audienceIds, variations, forcedVariations,
     self.groupPolicy = groupPolicy
 
 
+class FeatureFlag(BaseEntity):
+
+  class Type(object):
+    BOOLEAN = 'boolean'
+    DOUBLE = 'double'
+    INTEGER = 'integer'
+    STRING = 'string'
+
+
+  def __init__(self, id, key, type, defaultValue, **kwargs):
+    self.id = id
+    self.key = key
+    self.type = type
+    self.defaultValue = defaultValue
+
+
 class Group(BaseEntity):
 
   def __init__(self, id, policy, experiments, trafficAllocation, **kwargs):
@@ -69,6 +85,8 @@ def __init__(self, id, policy, experiments, trafficAllocation, **kwargs):
 
 class Variation(BaseEntity):
 
-  def __init__(self, id, key, **kwargs):
+  def __init__(self, id, key, variables=None, featureFlagMap=None, **kwargs):
     self.id = id
     self.key = key
+    self.variables = variables or []
+    self.featureFlagMap = featureFlagMap or {}

optimizely/event_builder.py

@@ -32,9 +32,8 @@ def __init__(self, url, params, http_verb=None, headers=None):
 class BaseEventBuilder(object):
   """ Base class which encapsulates methods to build events for tracking impressions and conversions. """
 
-  def __init__(self, config, bucketer):
+  def __init__(self, config):
     self.config = config
-    self.bucketer = bucketer
     self.params = {}
 
   @abstractproperty
@@ -97,7 +96,7 @@ def _add_common_params(self, user_id, attributes):
 
 
 class EventBuilder(BaseEventBuilder):
-  """ Class which encapsulates methods to build events for tracking 
+  """ Class which encapsulates methods to build events for tracking
   impressions and conversions using the new endpoints. """
 
   IMPRESSION_ENDPOINT = 'https://logx.optimizely.com/log/decision'
@@ -183,14 +182,13 @@ def _add_required_params_for_impression(self, experiment, variation_id):
       self.EventParams.IS_LAYER_HOLDBACK: False
     }
 
-  def _add_required_params_for_conversion(self, event_key, user_id, event_tags, valid_experiments):
+  def _add_required_params_for_conversion(self, event_key, event_tags, decisions):
     """ Add parameters that are required for the conversion event to register.
 
     Args:
       event_key: Key representing the event which needs to be recorded.
-      user_id: ID for user.
       event_tags: Dict representing metadata associated with the event.
-      valid_experiments: List of tuples representing valid experiments for the event.
+      decisions: List of tuples representing valid experiments IDs and variation IDs.
     """
 
     self.params[self.EventParams.IS_GLOBAL_HOLDBACK] = False
@@ -219,19 +217,18 @@ def _add_required_params_for_conversion(self, event_key, user_id, event_tags, va
         self.params[self.EventParams.EVENT_FEATURES].append(event_feature)
 
     self.params[self.EventParams.LAYER_STATES] = []
-    for experiment in valid_experiments:
-      variation = self.bucketer.bucket(experiment, user_id)
-      if variation:
-        self.params[self.EventParams.LAYER_STATES].append({
-          self.EventParams.LAYER_ID: experiment.layerId,
-          self.EventParams.REVISION: self.config.get_revision(),
-          self.EventParams.ACTION_TRIGGERED: True,
-          self.EventParams.DECISION: {
-            self.EventParams.EXPERIMENT_ID: experiment.id,
-            self.EventParams.VARIATION_ID: variation.id,
-            self.EventParams.IS_LAYER_HOLDBACK: False
-          }
-        })
+    for experiment_id, variation_id in decisions:
+      experiment = self.config.get_experiment_from_id(experiment_id)
+      self.params[self.EventParams.LAYER_STATES].append({
+        self.EventParams.LAYER_ID: experiment.layerId,
+        self.EventParams.REVISION: self.config.get_revision(),
+        self.EventParams.ACTION_TRIGGERED: True,
+        self.EventParams.DECISION: {
+          self.EventParams.EXPERIMENT_ID: experiment.id,
+          self.EventParams.VARIATION_ID: variation_id,
+          self.EventParams.IS_LAYER_HOLDBACK: False
+        }
+      })
 
     self.params[self.EventParams.EVENT_ID] = self.config.get_event(event_key).id
     self.params[self.EventParams.EVENT_NAME] = event_key
@@ -257,23 +254,23 @@ def create_impression_event(self, experiment, variation_id, user_id, attributes)
                  http_verb=self.HTTP_VERB,
                  headers=self.HTTP_HEADERS)
 
-  def create_conversion_event(self, event_key, user_id, attributes, event_tags, valid_experiments):
+  def create_conversion_event(self, event_key, user_id, attributes, event_tags, decisions):
     """ Create conversion Event to be sent to the logging endpoint.
 
     Args:
       event_key: Key representing the event which needs to be recorded.
       user_id: ID for user.
       attributes: Dict representing user attributes and values.
       event_tags: Dict representing metadata associated with the event.
-      valid_experiments: List of tuples representing valid experiments for the event.
+      decisions: List of tuples representing experiments IDs and variation IDs.
 
     Returns:
       Event object encapsulating the conversion event.
     """
 
     self.params = {}
     self._add_common_params(user_id, attributes)
-    self._add_required_params_for_conversion(event_key, user_id, event_tags, valid_experiments)
+    self._add_required_params_for_conversion(event_key, event_tags, decisions)
     return Event(self.CONVERSION_ENDPOINT,
                  self.params,
                  http_verb=self.HTTP_VERB,

optimizely/helpers/experiment.py

@@ -25,20 +25,3 @@ def is_experiment_running(experiment):
   """
 
   return experiment.status in ALLOWED_EXPERIMENT_STATUS
-
-
-def is_user_in_forced_variation(forced_variations, user_id):
-  """ Determine if the user is in a forced variation.
-
-  Args:
-    forced_variations: Dict representing forced variations for the experiment.
-    user_id: User to check for in whitelist.
-
-  Returns:
-    Boolean depending on whether user is in forced variation or not.
-  """
-
-  if forced_variations and user_id in forced_variations:
-    return True
-
-  return False