kameleoon-client-python 3.0.0__tar.gz → 3.2.0__tar.gz

{kameleoon-client-python-3.0.0 → kameleoon-client-python-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: kameleoon-client-python
-Version: 3.0.0
+Version: 3.2.0
 Summary: Kameleoon Client Python Software Development Kit.
 Home-page: https://developers.kameleoon.com/python-sdk.html
 Author: Kameleoon
@@ -9,14 +9,12 @@ License: GPLv3
 Platform: UNKNOWN
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
-Requires-Python: >=3.6.0
+Requires-Python: >=3.8.0
 Description-Content-Type: text/markdown
 Provides-Extra: test
 
@@ -31,7 +29,6 @@ Our SDK gives you the possibility of running experiments and activating feature
 
 You can refer to the [SDK reference](https://developers.kameleoon.com/python-sdk.html#reference) to check out all possible features of the SDK. Also make sure you check out our [Getting started tutorial](https://developers.kameleoon.com/python-sdk.html#getting-started) which we have prepared to walk you through the installation and implementation.
 
-
 #### Additional configuration
 
 You should provide credentials for the Kameleoon SDK via a configuration file,
@@ -41,17 +38,14 @@ file can be obtained here. We suggest to install this file to the default path o
 passing the path as an argument to the KameleoonClient class.
 With the current version of the Python SDK, those are the available keys:
 
-* `client_id: String`:  a client_id is required for authentication to the Kameleoon service.
-* `client_secret: String`: a client_secret is required for authentication to the Kameleoon service.
-* `actions_configuration_refresh_interval: int`: this specifies the refresh interval, in minutes,
-  of the configuration for experiments and feature flags (the active experiments and feature
-  flags are fetched from the Kameleoon servers). It means that once you launch an experiment,
-  pause it, or stop it the changes can take (at most) the duration of this interval to be
-  propagated in production to your servers. If not specified, the default interval
-  is 60 minutes.
-* `visitor_data_maximum_size: int`: this specifies the maximum amount of memory that the hash
-  holding all the visitor data (in particular custom data) can take (in MB).
-  If not specified, the default size is 500MB.
+- **client_id**: a `client_id` is required for authentication to the Kameleoon service.
+- **client_secret**: a `client_secret` is required for authentication to the Kameleoon service.
+- **refresh_interval_minute**: specifies the refresh interval, in minutes, of the configuration for feature flags (the active feature flags are fetched from the Kameleoon servers). It means that once you launch an experiment, pause it, or stop it, the changes can take (at most) the duration of this interval to be propagated in production to your servers. If not specified, the default interval is 60 minutes.
+- **session_duration_minute**: sets the time interval that Kameleoon stores the visitor and their associated data in memory (RAM). Note that increasing the session duration increases the amount of RAM that needs to be allocated to store visitor data. The default session duration is 30 minutes.
+- **default_timeout_millisecond**: specifies the timeout, in milliseconds for network requests from the SDK. It is recommended to set the value to 30 seconds or more if you do not have a stable connection. The default value is 10 seconds. Some methods have their own parameters for timeouts, but if you do not specify them explicitly, this value is used.
+- **top_level_domain**: the current top-level domain for your website. Kameleoon uses this information to set the corresponding cookie on the top-level domain. This field is mandatory.
+- **environment**: an option specifying which feature flag configuration will be used, by default each feature flag is split into **production**, **staging**, **development**. If not specified, will be set to **default value** of **production**. [More information](https://www.kameleoon.com/en/blog/configure-your-feature-flags-and-launch-your-releases-using-next-level-multi-environment)
+- **multi_threading**: an option of type **bool** indicating whether threads can be used for network requests. By default, the option is **False** and everything is executed in one thread to avoid performance issues with GIL if (C)Python interpreter is using. Possible values: **True** , **False**.
 
 
 ### Initializing the Kameleoon client
@@ -67,22 +61,36 @@ between your application and the Kameleoon platform.
 It includes all the methods and properties you will need to run an experiment.
 
 ```python
-from kameleoon import KameleoonClient
+from kameleoon import KameleoonClient, KameleoonClientConfig, KameleoonClientFactory
 
 SITE_CODE = 'a8st4f59bj'
 
-kameleoon_client = KameleoonClient(SITE_CODE)
-
-kameleoon_client = KameleoonClient(SITE_CODE, configuration_path='/etc/kameleoon/client.yaml')
-
-kameleoon_client = KameleoonClient(SITE_CODE)
-
-kameleoon_client = KameleoonClient(SITE_CODE, logger=MyLogger)
+# Option 1
+kameleoon_client = KameleoonClientFactory.create(SITE_CODE, config_path='/etc/kameleoon/client-python.yaml')
+
+# Option 2
+configuration_object = KameleoonClientConfig.read_from_yaml('/etc/kameleoon/client-python.yaml')
+configuration_object.set_logger(my_logger)
+kameleoon_client = KameleoonClientFactory.create(SITE_CODE, configuration_object)
+
+# Option 3
+configuration_object = KameleoonClientConfig(
+    "client-id",  # required
+    "client-secret",  # required
+    refresh_interval_minute=60,  # (in minutes) optional, default: 60 minutes
+    session_duration_minute=30,  # (in minutes) optional, default: 30 minutes
+    default_timeout_millisecond=10000,  # (in milliseconds) optional, default: 10000 milliseconds
+    environment="production",  # optional, possible values: "production" / "staging" / "development" / "staging", default: None
+    top_level_domain="example.com",
+    multi_threading=False,  # optional, default: False
+    logger=my_logger,  # optional, default: standard kameleoon logger
+)
+kameleoon_client = KameleoonClientFactory.create(SITE_CODE, configuration_object)
 ```
 
-### Triggering an experiment
+### Use Feature flag
 
-Running an A/B experiment on your Python application means bucketing your visitors
+Running an feature flag on your Python application means bucketing your visitors
 into several groups (one per variation). The SDK takes care of this bucketing (and the associated reporting)
 automatically.
 
@@ -92,41 +100,25 @@ variation (most likely a returning visitor that has already been exposed to the
 then it will return the previous variation assigned for the given experiment.
 
 ```python
-visitor_code = kameleoon_client.get_visitor_code(cookies_readonly=request.COOKIES)
-variation_id = 0
-try:
-    variation_id = kameleoon_client.trigger_experiment(visitor_code, 135471)
-except NotAllocated as ex:
-    # The user triggered the experiment, but did not activate it.
-    # Usually, this happens because the user has been associated
-    # with excluded traffic
-    variation_id = 0
-    client.logger.error(ex)
-except NotTargeted as ex:
-    # The user did not trigger the experiment, as the associated
-    # targeting segment conditions were not fulfilled.
-    # He should see the reference variation
-    variation_id = 0
-    client.logger.error(ex)
-except ExperimentConfigurationNotFound as ex:
-    # The user will not be counted into the experiment,
-    # but should see the reference variation
-    variation_id = 0
-    client.logger.error(ex)
-
-recommended_products_number = 5
-# This is the default / reference number of products to display
-
-if variation_id == 148382:
-    # We are changing number of recommended products for this variation to 10
-    recommended_products_number = 10
-elif variation_id == 187791:
-    # We are changing number of recommended products for this variation to 8
-    recommended_products_number = 8
-
-# Here you should have code to generate the HTML page back to the client,
-# where recommendedProductsNumber will be used
-response = JsonResponse({...})
+visitor_code = kameleoon_client.get_visitor_code(request.COOKIES)
+
+feature_key = "feature_key"
+variation_key = ""
+
+try
+    variation_key = kameleoon_client.get_feature_variation_key(visitor_code, feature_key)
+    if variation_key == 'on':
+        # main variation key is selected for visitorCode
+    elif variation_key == 'alternative_variation':
+        # alternative variation key
+    else:
+        # default variation key
+except FeatureNotFound as ex:
+    # The user will not be counted into the experiment, but should see the reference variation
+except VisitorCodeInvalid as ex:
+    # The visitor code which you passed to the method isn't valid and can't be accepted by SDK
+except FeatureEnvironmentDisabled as ex:
+    # The feature flag is disabled for certain environments
 ```
 
 ### How to use Kameleoon SDK with Django
@@ -192,49 +184,44 @@ client = kameleoon_app.kameleoon_client
 from django.apps import apps
 from django.http import JsonResponse
 
-from kameleoon.exceptions import NotAllocated, NotTargeted, ExperimentConfigurationNotFound
 
 kameleoon_app = apps.get_app_config('your_app')
 client = kameleoon_app.kameleoon_client
 
 def view(request):
-    visitor_code = client.get_visitor_code(cookies_readonly=request.COOKIES)
-    variation_id = 0
-    try:
-        variation_id = client.trigger_experiment(visitor_code, 135471)
-    except NotAllocated as ex:
-        # The user triggered the experiment, but did not activate it.
-        # Usually, this happens because the user has been associated
-        # with excluded traffic
-        variation_id = 0
-        client.logger.error(ex)
-    except NotTargeted as ex:
-        # The user did not trigger the experiment, as the associated
-        # targeting segment conditions were not fulfilled.
-        # He should see the reference variation
-        variation_id = 0
-        client.logger.error(ex)
-    except ExperimentConfigurationNotFound as ex:
-        # The user will not be counted into the experiment,
-        # but should see the reference variation
-        variation_id = 0
-        client.logger.error(ex)
+    simple_cookies = SimpleCookie()
+    simple_cookies.load(request.COOKIES)
+
+    visitor_code = kameleoon_client.get_visitor_code(cookies=simple_cookies)
+
+    feature_key = "feature_key"
+    variation_key = ""
 
     recommended_products_number = 5
     # This is the default / reference number of products to display
 
-    if variation_id == 148382:
-        # We are changing number of recommended products for this variation to 10
-        recommended_products_number = 10
-    elif variation_id == 187791:
-        # We are changing number of recommended products for this variation to 8
-        recommended_products_number = 8
+    try
+        variation_key = kameleoon_client.get_feature_variation_key(visitor_code, feature_key)
+        if variation_key == 'on':
+            # We are changing number of recommended products for this variation to 10
+            recommended_products_number = 10
+        elif variation_key == 'alternative_variation':
+            # We are changing number of recommended products for this variation to 20
+            recommended_products_number = 20
+        else:
+            # default variation key
+    except FeatureNotFound as ex:
+        # The user will not be counted into the experiment, but should see the reference variation
+    except VisitorCodeInvalid as ex:
+        # The visitor code which you passed to the method isn't valid and can't be accepted by SDK
+    except FeatureEnvironmentDisabled as ex:
+        # The feature flag is disabled for certain environments
 
     # Here you should have code to generate the HTML page back to the client,
     # where recommendedProductsNumber will be used
     response = JsonResponse({...})
     # set a cookie
-    response.set_cookie(**kameleoon_cookie)
+    response.set_cookie(simple_cookies.output())
 
     return response
 ```
@@ -250,11 +237,9 @@ You need to pass the visitor_code and goal_id parameters so we can correctly
 track conversions for this particular visitor.
 
 ```python
-visitor_code = client.get_visitor_code(cookies_readonly=request.COOKIES)
+visitor_code = client.get_visitor_code(request.COOKIES)
 goal_id = 83023
-client.track_conversion(visitor_code, goal_id )
+client.track_conversion(visitor_code, goal_id)
 ```
 
 
-
-

{kameleoon-client-python-3.0.0 → kameleoon-client-python-3.2.0}/README.md

@@ -8,7 +8,6 @@ Our SDK gives you the possibility of running experiments and activating feature
 
 You can refer to the [SDK reference](https://developers.kameleoon.com/python-sdk.html#reference) to check out all possible features of the SDK. Also make sure you check out our [Getting started tutorial](https://developers.kameleoon.com/python-sdk.html#getting-started) which we have prepared to walk you through the installation and implementation.
 
-
 #### Additional configuration
 
 You should provide credentials for the Kameleoon SDK via a configuration file,
@@ -18,17 +17,14 @@ file can be obtained here. We suggest to install this file to the default path o
 passing the path as an argument to the KameleoonClient class.
 With the current version of the Python SDK, those are the available keys:
 
-* `client_id: String`:  a client_id is required for authentication to the Kameleoon service.
-* `client_secret: String`: a client_secret is required for authentication to the Kameleoon service.
-* `actions_configuration_refresh_interval: int`: this specifies the refresh interval, in minutes,
-  of the configuration for experiments and feature flags (the active experiments and feature
-  flags are fetched from the Kameleoon servers). It means that once you launch an experiment,
-  pause it, or stop it the changes can take (at most) the duration of this interval to be
-  propagated in production to your servers. If not specified, the default interval
-  is 60 minutes.
-* `visitor_data_maximum_size: int`: this specifies the maximum amount of memory that the hash
-  holding all the visitor data (in particular custom data) can take (in MB).
-  If not specified, the default size is 500MB.
+- **client_id**: a `client_id` is required for authentication to the Kameleoon service.
+- **client_secret**: a `client_secret` is required for authentication to the Kameleoon service.
+- **refresh_interval_minute**: specifies the refresh interval, in minutes, of the configuration for feature flags (the active feature flags are fetched from the Kameleoon servers). It means that once you launch an experiment, pause it, or stop it, the changes can take (at most) the duration of this interval to be propagated in production to your servers. If not specified, the default interval is 60 minutes.
+- **session_duration_minute**: sets the time interval that Kameleoon stores the visitor and their associated data in memory (RAM). Note that increasing the session duration increases the amount of RAM that needs to be allocated to store visitor data. The default session duration is 30 minutes.
+- **default_timeout_millisecond**: specifies the timeout, in milliseconds for network requests from the SDK. It is recommended to set the value to 30 seconds or more if you do not have a stable connection. The default value is 10 seconds. Some methods have their own parameters for timeouts, but if you do not specify them explicitly, this value is used.
+- **top_level_domain**: the current top-level domain for your website. Kameleoon uses this information to set the corresponding cookie on the top-level domain. This field is mandatory.
+- **environment**: an option specifying which feature flag configuration will be used, by default each feature flag is split into **production**, **staging**, **development**. If not specified, will be set to **default value** of **production**. [More information](https://www.kameleoon.com/en/blog/configure-your-feature-flags-and-launch-your-releases-using-next-level-multi-environment)
+- **multi_threading**: an option of type **bool** indicating whether threads can be used for network requests. By default, the option is **False** and everything is executed in one thread to avoid performance issues with GIL if (C)Python interpreter is using. Possible values: **True** , **False**.
 
 
 ### Initializing the Kameleoon client
@@ -44,22 +40,36 @@ between your application and the Kameleoon platform.
 It includes all the methods and properties you will need to run an experiment.
 
 ```python
-from kameleoon import KameleoonClient
+from kameleoon import KameleoonClient, KameleoonClientConfig, KameleoonClientFactory
 
 SITE_CODE = 'a8st4f59bj'
 
-kameleoon_client = KameleoonClient(SITE_CODE)
-
-kameleoon_client = KameleoonClient(SITE_CODE, configuration_path='/etc/kameleoon/client.yaml')
-
-kameleoon_client = KameleoonClient(SITE_CODE)
-
-kameleoon_client = KameleoonClient(SITE_CODE, logger=MyLogger)
+# Option 1
+kameleoon_client = KameleoonClientFactory.create(SITE_CODE, config_path='/etc/kameleoon/client-python.yaml')
+
+# Option 2
+configuration_object = KameleoonClientConfig.read_from_yaml('/etc/kameleoon/client-python.yaml')
+configuration_object.set_logger(my_logger)
+kameleoon_client = KameleoonClientFactory.create(SITE_CODE, configuration_object)
+
+# Option 3
+configuration_object = KameleoonClientConfig(
+    "client-id",  # required
+    "client-secret",  # required
+    refresh_interval_minute=60,  # (in minutes) optional, default: 60 minutes
+    session_duration_minute=30,  # (in minutes) optional, default: 30 minutes
+    default_timeout_millisecond=10000,  # (in milliseconds) optional, default: 10000 milliseconds
+    environment="production",  # optional, possible values: "production" / "staging" / "development" / "staging", default: None
+    top_level_domain="example.com",
+    multi_threading=False,  # optional, default: False
+    logger=my_logger,  # optional, default: standard kameleoon logger
+)
+kameleoon_client = KameleoonClientFactory.create(SITE_CODE, configuration_object)
 ```
 
-### Triggering an experiment
+### Use Feature flag
 
-Running an A/B experiment on your Python application means bucketing your visitors
+Running an feature flag on your Python application means bucketing your visitors
 into several groups (one per variation). The SDK takes care of this bucketing (and the associated reporting)
 automatically.
 
@@ -69,41 +79,25 @@ variation (most likely a returning visitor that has already been exposed to the
 then it will return the previous variation assigned for the given experiment.
 
 ```python
-visitor_code = kameleoon_client.get_visitor_code(cookies_readonly=request.COOKIES)
-variation_id = 0
-try:
-    variation_id = kameleoon_client.trigger_experiment(visitor_code, 135471)
-except NotAllocated as ex:
-    # The user triggered the experiment, but did not activate it.
-    # Usually, this happens because the user has been associated
-    # with excluded traffic
-    variation_id = 0
-    client.logger.error(ex)
-except NotTargeted as ex:
-    # The user did not trigger the experiment, as the associated
-    # targeting segment conditions were not fulfilled.
-    # He should see the reference variation
-    variation_id = 0
-    client.logger.error(ex)
-except ExperimentConfigurationNotFound as ex:
-    # The user will not be counted into the experiment,
-    # but should see the reference variation
-    variation_id = 0
-    client.logger.error(ex)
-
-recommended_products_number = 5
-# This is the default / reference number of products to display
-
-if variation_id == 148382:
-    # We are changing number of recommended products for this variation to 10
-    recommended_products_number = 10
-elif variation_id == 187791:
-    # We are changing number of recommended products for this variation to 8
-    recommended_products_number = 8
-
-# Here you should have code to generate the HTML page back to the client,
-# where recommendedProductsNumber will be used
-response = JsonResponse({...})
+visitor_code = kameleoon_client.get_visitor_code(request.COOKIES)
+
+feature_key = "feature_key"
+variation_key = ""
+
+try
+    variation_key = kameleoon_client.get_feature_variation_key(visitor_code, feature_key)
+    if variation_key == 'on':
+        # main variation key is selected for visitorCode
+    elif variation_key == 'alternative_variation':
+        # alternative variation key
+    else:
+        # default variation key
+except FeatureNotFound as ex:
+    # The user will not be counted into the experiment, but should see the reference variation
+except VisitorCodeInvalid as ex:
+    # The visitor code which you passed to the method isn't valid and can't be accepted by SDK
+except FeatureEnvironmentDisabled as ex:
+    # The feature flag is disabled for certain environments
 ```
 
 ### How to use Kameleoon SDK with Django
@@ -169,49 +163,44 @@ client = kameleoon_app.kameleoon_client
 from django.apps import apps
 from django.http import JsonResponse
 
-from kameleoon.exceptions import NotAllocated, NotTargeted, ExperimentConfigurationNotFound
 
 kameleoon_app = apps.get_app_config('your_app')
 client = kameleoon_app.kameleoon_client
 
 def view(request):
-    visitor_code = client.get_visitor_code(cookies_readonly=request.COOKIES)
-    variation_id = 0
-    try:
-        variation_id = client.trigger_experiment(visitor_code, 135471)
-    except NotAllocated as ex:
-        # The user triggered the experiment, but did not activate it.
-        # Usually, this happens because the user has been associated
-        # with excluded traffic
-        variation_id = 0
-        client.logger.error(ex)
-    except NotTargeted as ex:
-        # The user did not trigger the experiment, as the associated
-        # targeting segment conditions were not fulfilled.
-        # He should see the reference variation
-        variation_id = 0
-        client.logger.error(ex)
-    except ExperimentConfigurationNotFound as ex:
-        # The user will not be counted into the experiment,
-        # but should see the reference variation
-        variation_id = 0
-        client.logger.error(ex)
+    simple_cookies = SimpleCookie()
+    simple_cookies.load(request.COOKIES)
+
+    visitor_code = kameleoon_client.get_visitor_code(cookies=simple_cookies)
+
+    feature_key = "feature_key"
+    variation_key = ""
 
     recommended_products_number = 5
     # This is the default / reference number of products to display
 
-    if variation_id == 148382:
-        # We are changing number of recommended products for this variation to 10
-        recommended_products_number = 10
-    elif variation_id == 187791:
-        # We are changing number of recommended products for this variation to 8
-        recommended_products_number = 8
+    try
+        variation_key = kameleoon_client.get_feature_variation_key(visitor_code, feature_key)
+        if variation_key == 'on':
+            # We are changing number of recommended products for this variation to 10
+            recommended_products_number = 10
+        elif variation_key == 'alternative_variation':
+            # We are changing number of recommended products for this variation to 20
+            recommended_products_number = 20
+        else:
+            # default variation key
+    except FeatureNotFound as ex:
+        # The user will not be counted into the experiment, but should see the reference variation
+    except VisitorCodeInvalid as ex:
+        # The visitor code which you passed to the method isn't valid and can't be accepted by SDK
+    except FeatureEnvironmentDisabled as ex:
+        # The feature flag is disabled for certain environments
 
     # Here you should have code to generate the HTML page back to the client,
     # where recommendedProductsNumber will be used
     response = JsonResponse({...})
     # set a cookie
-    response.set_cookie(**kameleoon_cookie)
+    response.set_cookie(simple_cookies.output())
 
     return response
 ```
@@ -227,9 +216,7 @@ You need to pass the visitor_code and goal_id parameters so we can correctly
 track conversions for this particular visitor.
 
 ```python
-visitor_code = client.get_visitor_code(cookies_readonly=request.COOKIES)
+visitor_code = client.get_visitor_code(request.COOKIES)
 goal_id = 83023
-client.track_conversion(visitor_code, goal_id )
+client.track_conversion(visitor_code, goal_id)
 ```
-
-

kameleoon-client-python-3.2.0/kameleoon/configuration/__init__.py

@@ -0,0 +1,9 @@
+""" Imports kameleoon configurations objects """
+
+from .variable import Variable
+from .variation import Variation
+
+__all__ = [
+    "Variable",
+    "Variation",
+]

kameleoon-client-python-3.2.0/kameleoon/configuration/custom_data_info.py

@@ -0,0 +1,51 @@
+"""Custom data info"""
+
+from logging import Logger
+from typing import Optional, Dict, Union, Any, List
+
+
+class CustomDataInfo:
+    """Custom data info"""
+
+    SCOPE_VISITOR = "VISITOR"
+
+    def __init__(
+        self, custom_data: Optional[List[Dict[str, Union[str, int, Any]]]], logger: Optional[Logger] = None
+    ) -> None:
+        super().__init__()
+        self.__mapping_identifier_index = None
+        self.__local_only = set()
+        self.__visitor_scope = set()
+        if custom_data is not None:
+            for data in custom_data:
+                index = data.get("index")
+                if index is not None:
+                    index = int(index)
+                    if data.get("localOnly"):
+                        self.__local_only.add(index)
+                    if data.get("scope") == self.SCOPE_VISITOR:
+                        self.__visitor_scope.add(index)
+                    if data.get("isMappingIdentifier"):
+                        if bool(self.__mapping_identifier_index is not None) and logger is not None:
+                            logger.info(
+                                "More than one mapping identifier is set. Undefined behavior may occur" +
+                                " on cross-device reconciliation."
+                            )
+                        self.__mapping_identifier_index = index
+
+    def is_local_only(self, index: int) -> bool:
+        """Check for local only"""
+        return index in self.__local_only
+
+    def is_mapping_identifier(self, index: int) -> bool:
+        """Check for mapping identifier"""
+        return self.__mapping_identifier_index == index
+
+    def is_visitor_scope(self, index: int) -> bool:
+        """Check for visitor scope"""
+        return index in self.__visitor_scope
+
+    @property
+    def mapping_identifier_index(self) -> Optional[int]:
+        """Take mapping identifier index"""
+        return self.__mapping_identifier_index