kameleoon-client-python 3.6.1__tar.gz → 3.8.0__tar.gz

{kameleoon-client-python-3.6.1 → kameleoon-client-python-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: kameleoon-client-python
-Version: 3.6.1
+Version: 3.8.0
 Summary: Kameleoon Client Python Software Development Kit.
 Home-page: https://developers.kameleoon.com/python-sdk.html
 Author: Kameleoon

{kameleoon-client-python-3.6.1 → kameleoon-client-python-3.8.0}/kameleoon/configuration/data_file.py

@@ -3,10 +3,11 @@
 from typing import Any, Dict, Optional, Set
 from kameleoon.configuration import Variable
 from kameleoon.configuration.custom_data_info import CustomDataInfo
-from kameleoon.configuration.variation_by_exposition import VariationByExposition
+from kameleoon.configuration.experiment import Experiment
 from kameleoon.configuration.feature_flag import FeatureFlag
 from kameleoon.configuration.rule import Rule
 from kameleoon.configuration.settings import Settings
+from kameleoon.configuration.variation_by_exposition import VariationByExposition
 from kameleoon.exceptions import FeatureNotFound, FeatureEnvironmentDisabled
 from kameleoon.logging.kameleoon_logger import KameleoonLogger
 
@@ -31,7 +32,8 @@ class DataFile:
             for jobj in configuration.get("featureFlags") or []
         }
         custom_data_info = CustomDataInfo(configuration.get("customData"))
-        data_file = DataFile(environment, settings, feature_flags, custom_data_info)
+        holdout = Experiment.from_json(configuration["holdout"]) if "holdout" in configuration else None
+        data_file = DataFile(environment, settings, feature_flags, custom_data_info, holdout)
         return data_file
 
     # pylint: disable=R0913
@@ -41,10 +43,12 @@ class DataFile:
         settings: Settings,
         feature_flags: Dict[str, FeatureFlag],
         custom_data_info: CustomDataInfo,
+        holdout: Optional[Experiment] = None,
     ) -> None:
         KameleoonLogger.debug(
-            'CALL: DataFile(environment: %s, settings: %s, feature_flags: %s, custom_data_info: %s)',
-            environment, settings, feature_flags, custom_data_info)
+            'CALL: DataFile(environment: %s, settings: %s, feature_flags: %s, custom_data_info: %s, holdout: %s)',
+            environment, settings, feature_flags, custom_data_info, holdout
+        )
         self.__environment = environment  # pylint: disable=W0238
         self.__settings = settings
         self.__feature_flags: Dict[str, FeatureFlag] = feature_flags
@@ -56,13 +60,16 @@ class DataFile:
         )
         self.__variation_by_id: Dict[int, VariationByExposition] = {}
         self.__rule_by_segment_id: Dict[int, Rule] = {}
+        self.__rule_info_by_exp_id: Dict[int, DataFile.RuleInfo] = {}
         self.__feature_flag_by_id: Dict[int, FeatureFlag] = {}
         self.__experiment_ids_with_js_css_variable: Set[int] = set()
         self.__collect_indices()
         self.__custom_data_info = custom_data_info
+        self.__holdout = holdout
         KameleoonLogger.debug(
-            'RETURN: DataFile.new(environment: %s, settings: %s, feature_flags: %s, custom_data_info: %s)',
-            environment, settings, feature_flags, custom_data_info)
+            'RETURN: DataFile.new(environment: %s, settings: %s, feature_flags: %s, custom_data_info: %s, holdout: %s)',
+            environment, settings, feature_flags, custom_data_info
+        )
 
     @property
     def settings(self) -> Settings:
@@ -84,6 +91,11 @@ class DataFile:
         """Returns dictionary of all rule stored by segment id"""
         return self.__rule_by_segment_id
 
+    @property
+    def rule_info_by_exp_id(self) -> Dict[int, "DataFile.RuleInfo"]:
+        """Returns dictionary of all rule related info stored by experiment id"""
+        return self.__rule_info_by_exp_id
+
     @property
     def variation_by_id(self) -> Dict[int, VariationByExposition]:
         """Returns dictionary of all variations stored by id"""
@@ -108,9 +120,14 @@ class DataFile:
 
     @property
     def custom_data_info(self) -> CustomDataInfo:
-        """Returns custom data info for mapping device`"""
+        """Returns custom data info for mapping device"""
         return self.__custom_data_info
 
+    @property
+    def holdout(self) -> Optional[Experiment]:
+        """Returns holdout"""
+        return self.__holdout
+
     def has_experiment_js_css_variable(self, experiment_id: int) -> bool:
         """Returns `True` if the experiment has a JS or CSS variable, otherwise returns `False`"""
         return experiment_id in self.__experiment_ids_with_js_css_variable
@@ -122,9 +139,10 @@ class DataFile:
                 has_feature_flag_variable_js_css = self.__has_feature_flag_variable_js_css(feature_flag)
                 for rule in feature_flag.rules:
                     self.__rule_by_segment_id[rule.segment_id] = rule
+                    self.__rule_info_by_exp_id[rule.experiment.id_] = DataFile.RuleInfo(feature_flag, rule)
                     if has_feature_flag_variable_js_css:
-                        self.__experiment_ids_with_js_css_variable.add(rule.experiment_id)
-                    for variation in rule.variation_by_exposition:
+                        self.__experiment_ids_with_js_css_variable.add(rule.experiment.id_)
+                    for variation in rule.experiment.variations_by_exposition:
                         if variation.variation_id is not None:
                             self.__variation_by_id[variation.variation_id] = variation
 
@@ -146,3 +164,20 @@ class DataFile:
             f"settings:{self.__settings}"
             f"}}"
         )
+
+    class RuleInfo:
+        """Aggregates some information related to a specific rule"""
+
+        def __init__(self, feature_flag: FeatureFlag, rule: Rule) -> None:
+            self.__feature_flag = feature_flag
+            self.__rule = rule
+
+        @property
+        def feature_flag(self) -> FeatureFlag:
+            """Returns the feature flag"""
+            return self.__feature_flag
+
+        @property
+        def rule(self) -> Rule:
+            """Returns the rule"""
+            return self.__rule

kameleoon-client-python-3.8.0/kameleoon/configuration/experiment.py

@@ -0,0 +1,46 @@
+"""Kameleoon Configuration"""
+
+from typing import Any, List, Dict, Optional
+from kameleoon.configuration.variation_by_exposition import VariationByExposition
+from kameleoon.exceptions import FeatureVariationNotFound
+
+
+class Experiment:
+    """Experiment"""
+
+    def __init__(self, id_: int, variations_by_exposition: List[VariationByExposition]) -> None:
+        self.id_ = id_
+        self.variations_by_exposition = variations_by_exposition
+        self.first_variation = variations_by_exposition[0] if len(variations_by_exposition) > 0 else None
+
+    @staticmethod
+    def from_json(dict_json: Dict[str, Any]) -> "Experiment":
+        """Creates a new instance of `Experiment` from a json object"""
+        id_ = dict_json.get("experimentId", 0)
+        variations_by_exposition: List[VariationByExposition] = VariationByExposition.from_array(
+            dict_json.get("variationByExposition", [])
+        )
+        return Experiment(id_, variations_by_exposition)
+
+    def get_variation(self, hash_double: float) -> Optional[VariationByExposition]:
+        """Calculates the variation key for the given hash of visitor"""
+
+        total = 0.0
+        for var_by_exp in self.variations_by_exposition:
+            total += var_by_exp.exposition
+            if total >= hash_double:
+                return var_by_exp
+        return None
+
+    def get_variation_by_key(self, variation_key: str) -> VariationByExposition:
+        """
+        Finds variation with a passed variation key.
+        Raises the `FeatureVariationNotFound` exception if such variation does not exist.
+        """
+        for var_by_exp in self.variations_by_exposition:
+            if var_by_exp.variation_key == variation_key:
+                return var_by_exp
+        raise FeatureVariationNotFound("'#{variation_key}'")
+
+    def __str__(self) -> str:
+        return f"Experiment{{id:{self.id_}}}"

{kameleoon-client-python-3.6.1 → kameleoon-client-python-3.8.0}/kameleoon/configuration/rule.py

@@ -1,8 +1,8 @@
 """Kameleoon Configuration"""
 
 from typing import Any, List, Dict, Optional
+from kameleoon.configuration.experiment import Experiment
 from kameleoon.configuration.rule_type import RuleType, rule_type_from_literal
-from kameleoon.configuration.variation_by_exposition import VariationByExposition
 from kameleoon.targeting.models import Segment
 
 
@@ -23,26 +23,12 @@ class Rule:
         type_literal: str = dict_json.get("type", "")
         self.type = rule_type_from_literal(type_literal)
         self.exposition: float = dict_json.get("exposition", 0.0)
-        self.experiment_id: int = dict_json.get("experimentId", 0)
+        self.experiment = Experiment.from_json(dict_json)
         self.respool_time: Optional[int] = dict_json.get("respoolTime", None)
-        self.variation_by_exposition: List[VariationByExposition] = VariationByExposition.from_array(
-            dict_json.get("variationByExposition", [])
-        )
-        self.first_variation = self.variation_by_exposition[0] if len(self.variation_by_exposition) > 0 else None
         segment = dict_json.get("segment")
         self.targeting_segment: Optional[Segment] = Segment(segment) if segment else None
         self.segment_id: int = self.targeting_segment.id_ if self.targeting_segment else -1
 
-    def get_variation(self, hash_double: float) -> Optional[VariationByExposition]:
-        """Calculates the variation key for the given hash of visitor"""
-
-        total = 0.0
-        for var_by_exp in self.variation_by_exposition:
-            total += var_by_exp.exposition
-            if total >= hash_double:
-                return var_by_exp
-        return None
-
     @property
     def is_experimentation(self) -> bool:
         """Return `true` if rule is `experimentation` type"""

{kameleoon-client-python-3.6.1 → kameleoon-client-python-3.8.0}/kameleoon/data/data.py

@@ -20,6 +20,8 @@ class DataType(IntEnum):
     VISITOR_VISITS = 11
     KCS_HEAT = 12
     UNIQUE_IDENTIFIER = 13
+    FORCED_EXPERIMENT_VARIATION = 14
+    FORCED_FEATURE_VARIATION = 15
 
 
 class BaseData:

kameleoon-client-python-3.8.0/kameleoon/data/manager/forced_experiment_variation.py

@@ -0,0 +1,49 @@
+"""Forced Experiment Variation"""
+
+from typing import Any, cast
+from kameleoon.configuration.rule import Rule
+from kameleoon.configuration.variation_by_exposition import VariationByExposition
+from kameleoon.data.data import DataType
+from kameleoon.data.manager.forced_variation import ForcedVariation
+
+
+class ForcedExperimentVariation(ForcedVariation):
+    """Represents a forced experiment variation"""
+
+    def __init__(
+        self, rule: Rule, var_by_exp: VariationByExposition, force_targeting: bool
+    ) -> None:
+        super().__init__(rule, var_by_exp)
+        self.__force_targeting = force_targeting
+
+    @property
+    def data_type(self) -> DataType:
+        return DataType.FORCED_EXPERIMENT_VARIATION
+
+    @property
+    def rule(self) -> Rule:
+        """Returns the rule"""
+        return self._rule or cast(Rule, self._rule)
+
+    @property
+    def var_by_exp(self) -> VariationByExposition:
+        """Returns the variation by exposition"""
+        return self._var_by_exp or cast(VariationByExposition, self._var_by_exp)
+
+    @property
+    def force_targeting(self) -> bool:
+        """Returns the force targeting flag's state"""
+        return self.__force_targeting
+
+    def __eq__(self, value: Any) -> bool:
+        return super().__eq__(value) and isinstance(value, ForcedExperimentVariation) and \
+            (self.__force_targeting == value.force_targeting)
+
+    def __str__(self) -> str:
+        return (
+            "ForcedExperimentVariation{"
+            f"rule:{self._rule},"
+            f"var_by_exp:{self._var_by_exp},"
+            f"force_targeting:{self.__force_targeting},"
+            "}"
+        )

kameleoon-client-python-3.8.0/kameleoon/data/manager/forced_feature_variation.py

@@ -0,0 +1,46 @@
+"""Forced Feature Variation"""
+
+from typing import Any, Optional
+from kameleoon.configuration.rule import Rule
+from kameleoon.configuration.variation_by_exposition import VariationByExposition
+from kameleoon.data.data import DataType
+from kameleoon.data.manager.forced_variation import ForcedVariation
+
+
+class ForcedFeatureVariation(ForcedVariation):
+    """Represents a forced feature variation"""
+
+    def __init__(
+        self, feature_key: str, rule: Optional[Rule], var_by_exp: Optional[VariationByExposition], simulated: bool
+    ) -> None:
+        super().__init__(rule, var_by_exp)
+        self.__feature_key = feature_key
+        self.__simulated = simulated
+
+    @property
+    def data_type(self) -> DataType:
+        return DataType.FORCED_FEATURE_VARIATION
+
+    @property
+    def feature_key(self) -> str:
+        """Returns the feature key"""
+        return self.__feature_key
+
+    @property
+    def simulated(self) -> bool:
+        """Returns the simulated flag's state"""
+        return self.__simulated
+
+    def __eq__(self, value: Any) -> bool:
+        return super().__eq__(value) and isinstance(value, ForcedFeatureVariation) and \
+            (self.__feature_key == value.feature_key) and (self.__simulated == value.simulated)
+
+    def __str__(self) -> str:
+        return (
+            "ForcedFeatureVariation{"
+            f"feature_key:'{self.__feature_key}',"
+            f"rule:{self._rule},"
+            f"var_by_exp:{self._var_by_exp},"
+            f"simulated:{self.__simulated},"
+            "}"
+        )

kameleoon-client-python-3.8.0/kameleoon/data/manager/forced_variation.py

@@ -0,0 +1,33 @@
+"""Forced Variation"""
+
+from typing import Any, Optional
+from kameleoon.configuration.rule import Rule
+from kameleoon.configuration.variation_by_exposition import VariationByExposition
+from kameleoon.data.data import BaseData, DataType
+
+
+class ForcedVariation(BaseData):
+    """Represents a forced variation"""
+
+    def __init__(self, rule: Optional[Rule], var_by_exp: Optional[VariationByExposition]) -> None:
+        super().__init__()
+        self._rule = rule
+        self._var_by_exp = var_by_exp
+
+    @property
+    def data_type(self) -> DataType:
+        raise NotImplementedError
+
+    @property
+    def rule(self) -> Optional[Rule]:
+        """Returns the rule"""
+        return self._rule
+
+    @property
+    def var_by_exp(self) -> Optional[VariationByExposition]:
+        """Returns the variation by exposition"""
+        return self._var_by_exp
+
+    def __eq__(self, value: Any) -> bool:
+        return isinstance(value, ForcedVariation) and \
+            (self._rule == value._rule) and (self._var_by_exp == value._var_by_exp)

{kameleoon-client-python-3.6.1 → kameleoon-client-python-3.8.0}/kameleoon/data/manager/visitor.py

@@ -1,6 +1,6 @@
 """Visitor"""
 from threading import Lock
-from typing import Any, Callable, Optional, Dict, List, Iterator, cast
+from typing import Any, Callable, Optional, Dict, List, Iterator, Iterable, cast
 
 from kameleoon.data.visitor_visits import VisitorVisits
 from kameleoon.data.data import Data
@@ -17,6 +17,8 @@ from kameleoon.data.page_view import PageView
 from kameleoon.data.unique_identifier import UniqueIdentifier
 from kameleoon.data.user_agent import UserAgent
 from kameleoon.data.manager.assigned_variation import AssignedVariation
+from kameleoon.data.manager.forced_experiment_variation import ForcedExperimentVariation
+from kameleoon.data.manager.forced_feature_variation import ForcedFeatureVariation
 from kameleoon.data.manager.page_view_visit import PageViewVisit
 from kameleoon.logging.kameleoon_logger import KameleoonLogger
 from kameleoon.network.sendable import Sendable
@@ -26,7 +28,7 @@ EMPTY_DICT: Dict[Any, Any] = {}
 EMPTY_LIST: List[Any] = []
 
 
-class Visitor:
+class Visitor:  # pylint: disable=R0904
     """Visitor"""
     def __init__(self, source: Optional["Visitor"] = None) -> None:
         if source is None:
@@ -124,6 +126,45 @@ class Visitor:
         KameleoonLogger.debug('CALL/RETURN: Visitor.variations -> (variations: %s)', variations)
         return variations
 
+    def get_forced_feature_variation(self, feature_key: str) -> Optional[ForcedFeatureVariation]:
+        """
+        Returns an associated forced feature variation by its feature key if it is present.
+        Otherwise returns `None`.
+        """
+        KameleoonLogger.debug('CALL: Visitor.get_forced_feature_variation(feature_key: %s)', feature_key)
+        ffv = self._data.simulated_variations.get(feature_key) if self._data.simulated_variations else None
+        KameleoonLogger.debug(
+            'RETURN: Visitor.get_forced_feature_variation(feature_key: %s) -> (variation: %s)', feature_key, ffv
+        )
+        return ffv
+
+    def get_forced_experiment_variation(self, experiment_id: int) -> Optional[ForcedExperimentVariation]:
+        """
+        Returns an associated forced experiment variation by its experiment id if it is present.
+        Otherwise returns `None`.
+        """
+        KameleoonLogger.debug('CALL: Visitor.get_forced_experiment_variation(experiment_id: %s)', experiment_id)
+        fev = self._data.forced_variations.get(experiment_id) if self._data.forced_variations else None
+        KameleoonLogger.debug(
+            'RETURN: Visitor.get_forced_experiment_variation(experiment_id: %s) -> (variation: %s)', experiment_id, fev
+        )
+        return fev
+
+    def reset_forced_experiment_variation(self, experiment_id: int) -> None:
+        """Resets an associated forced experiment variation for some experiment id"""
+        KameleoonLogger.debug('CALL: Visitor.reset_forced_experiment_variation(experiment_id: %s)', experiment_id)
+        if self._data.forced_variations:
+            self._data.forced_variations.pop(experiment_id, None)
+        KameleoonLogger.debug('RETURN: Visitor.reset_forced_experiment_variation(experiment_id: %s)', experiment_id)
+
+    def update_simulated_variations(self, variations: Iterable[ForcedFeatureVariation]) -> None:
+        """Updates the associated simulated variations"""
+        if not (self._data.simulated_variations or variations):
+            return
+        KameleoonLogger.debug('CALL: Visitor.update_simulated_variations(variations: %s)', variations)
+        self._data.simulated_variations = {sv.feature_key: sv for sv in variations}
+        KameleoonLogger.debug('RETURN: Visitor.update_simulated_variations(variations: %s)', variations)
+
     @property
     def kcs_heat(self) -> Optional[KcsHeat]:
         """Returns the KCS heat data associated with this Visitor."""
@@ -217,6 +258,8 @@ class Visitor:
             self.page_view_visits: Optional[Dict[str, PageViewVisit]] = None
             self.conversions: Optional[List[Conversion]] = None
             self.variations: Optional[Dict[int, AssignedVariation]] = None
+            self.forced_variations: Optional[Dict[int, ForcedExperimentVariation]] = None
+            self.simulated_variations: Optional[Dict[str, ForcedFeatureVariation]] = None
             self.kcs_heat: Optional[KcsHeat] = None
             self.visitor_visits: Optional[VisitorVisits] = None
             self.mapping_identifier: Optional[str] = None
@@ -294,6 +337,18 @@ class Visitor:
         if context.overwrite or variation.experiment_id not in self.variations:
             self._data.variations[variation.experiment_id] = variation
 
+    def _add_forced_feature_variation(self, context: DataAddingContext) -> None:
+        ffv = cast(ForcedFeatureVariation, context.data)
+        if self._data.simulated_variations is None:
+            self._data.simulated_variations = {}
+        self._data.simulated_variations[ffv.feature_key] = ffv
+
+    def _add_forced_experiment_variation(self, context: DataAddingContext) -> None:
+        fev = cast(ForcedExperimentVariation, context.data)
+        if self._data.forced_variations is None:
+            self._data.forced_variations = {}
+        self._data.forced_variations[fev.rule.experiment.id_] = fev
+
     def _set_browser(self, context: DataAddingContext) -> None:
         if context.overwrite or self._data.browser is None:
             self._data.browser = cast(Browser, context.data)
@@ -372,5 +427,7 @@ class Visitor:
         KcsHeat: _set_kcs_heat,
         VisitorVisits: _set_visitor_visits,
         AssignedVariation: _add_variation,
+        ForcedFeatureVariation: _add_forced_feature_variation,
+        ForcedExperimentVariation: _add_forced_experiment_variation,
         UniqueIdentifier: _set_is_unique_identifier,
     }

{kameleoon-client-python-3.6.1 → kameleoon-client-python-3.8.0}/kameleoon/exceptions.py

@@ -70,6 +70,15 @@ class FeatureNotFound(NotFoundError):
         super().__init__(self.message)
 
 
+class FeatureExperimentNotFound(NotFoundError):  # //~ Derived from FeatureError in other SDKs
+    """Exception indicating that the requested experiment has not been found.
+    Check that the experiment's ID matches the provided one."""
+
+    def __init__(self, message=None) -> None:
+        self.message = "Experiment " + str(message)
+        super().__init__(self.message)
+
+
 class FeatureVariableNotFound(NotFoundError):
     """Exception indicating that the requested variable has not been found.
     Check that the variable's ID (or key) matches the one in your code."""

{kameleoon-client-python-3.6.1 → kameleoon-client-python-3.8.0}/kameleoon/helpers/functions.py

@@ -1,46 +1,8 @@
 """Helper functions"""
-import hashlib
 import json
-import math
 import sys
 from enum import Enum
-from typing import Dict, Any, Optional, Union, Type, TypeVar
-
-
-def obtain_hash_double(
-    visitor_code: str, respool_times=None, container_id: str = ""
-) -> float:
-    """Calculate the hash value for a given visitor_code"""
-    return _obtain_hash_double(visitor_code, respool_times, container_id)
-
-
-def obtain_hash_double_rule(
-    visitor_code: str, container_id: int, respool_time: Optional[int] = None
-) -> float:
-    """Calculate the hash value for feature flag v2 for a given visitor_code"""
-    return _obtain_hash_double(
-        visitor_code=visitor_code,
-        container_id=container_id,
-        suffix=str(respool_time) if respool_time else "",
-    )
-
-
-def _obtain_hash_double(
-    visitor_code: str,
-    respool_times=None,
-    container_id: Union[str, int] = "",
-    suffix: str = "",
-) -> float:
-    if respool_times is None:
-        respool_times = {}
-    identifier = visitor_code
-    identifier += str(container_id)
-    identifier += suffix
-    if respool_times:
-        identifier += "".join([str(v) for k, v in sorted(respool_times.items())])
-    return int(hashlib.sha256(identifier.encode("UTF-8")).hexdigest(), 16) / math.pow(
-        2, 256
-    )
+from typing import Dict, Any, Optional, Type, TypeVar
 
 
 def load_params_from_json(json_path) -> Dict[Any, Any]:

kameleoon-client-python-3.8.0/kameleoon/helpers/hasher.py

@@ -0,0 +1,24 @@
+"""Helper hash functions"""
+
+import hashlib
+import math
+from typing import Optional
+
+
+class Hasher:
+    """Hasher"""
+
+    @staticmethod
+    def obtain(
+        visitor_code: str, container_id: int, respool_time: Optional[int] = None
+    ) -> float:
+        """Calculate the hash value for feature flag v2 for a given visitor_code"""
+        identifier = visitor_code
+        identifier += str(container_id)
+        if respool_time:
+            identifier += str(respool_time)
+        return Hasher._calculate(identifier)
+
+    @staticmethod
+    def _calculate(str_to_hash: str) -> float:
+        return int(hashlib.sha256(str_to_hash.encode("UTF-8")).hexdigest(), 16) / math.pow(2, 256)