FeatureManagement 1.0.0__tar.gz → 2.0.0b1__tar.gz

{featuremanagement-1.0.0 → featuremanagement-2.0.0b1}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Release History
 
+## 2.0.0b1 (09/10/2024)
+
+* Adds support for Feature Variants.
+* Adds support for Telemetry.
+
 ## 1.0.0 (06/26/2024)
 
 Updated version to 1.0.0.

{featuremanagement-1.0.0 → featuremanagement-2.0.0b1/FeatureManagement.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: FeatureManagement
-Version: 1.0.0
+Version: 2.0.0b1
 Summary: A library for enabling/disabling features at runtime.
 Home-page: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/appconfiguration/feature-management
 Author: Microsoft Corporation
@@ -41,9 +41,8 @@ Classifier: License :: OSI Approved :: MIT License
 Requires-Python: >=3.6
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Provides-Extra: appinsights
-Requires-Dist: azure-monitor-opentelemetry<2.0.0,>=1.3.0; extra == "appinsights"
-Requires-Dist: azure-monitor-events-extension<2.0.0; extra == "appinsights"
+Provides-Extra: azuremonitor
+Requires-Dist: azure-monitor-events-extension<2.0.0; extra == "azuremonitor"
 
 # Microsoft Feature Management for Python
 
@@ -60,6 +59,7 @@ Feature management provides a way to develop and expose application functionalit
 ## Examples
 
 * [Python Application](https://github.com/microsoft/FeatureManagement-Python/blob/main/samples/feature_flag_sample.py)
+* [Python Application with Feature Variants](https://github.com/microsoft/FeatureManagement-Python/blob/main/samples/feature_variant_sample.py)
 * [Python Application with Azure App Configuration](https://github.com/microsoft/FeatureManagement-Python/blob/main/samples/feature_flag_with_azure_app_configuration_sample.py)
 * [Django Application](https://github.com/Azure/AppConfiguration/tree/main/examples/Python/python-django-webapp-sample)
 * [Flask Application](https://github.com/Azure/AppConfiguration/tree/main/examples/Python/python-flask-webapp-sample)

{featuremanagement-1.0.0 → featuremanagement-2.0.0b1}/FeatureManagement.egg-info/SOURCES.txt

@@ -17,20 +17,30 @@ featuremanagement/__init__.py
 featuremanagement/_defaultfilters.py
 featuremanagement/_featurefilters.py
 featuremanagement/_featuremanager.py
+featuremanagement/_featuremanagerbase.py
 featuremanagement/_version.py
 featuremanagement/py.typed
 featuremanagement/_models/__init__.py
+featuremanagement/_models/_allocation.py
 featuremanagement/_models/_constants.py
 featuremanagement/_models/_evaluation_event.py
 featuremanagement/_models/_feature_conditions.py
 featuremanagement/_models/_feature_flag.py
 featuremanagement/_models/_targeting_context.py
+featuremanagement/_models/_telemetry.py
+featuremanagement/_models/_variant.py
+featuremanagement/_models/_variant_assignment_reason.py
+featuremanagement/_models/_variant_reference.py
 featuremanagement/aio/__init__.py
 featuremanagement/aio/_defaultfilters.py
 featuremanagement/aio/_featurefilters.py
 featuremanagement/aio/_featuremanager.py
+featuremanagement/azuremonitor/__init__.py
+featuremanagement/azuremonitor/_send_telemetry.py
 samples/feature_flag_sample.py
 samples/feature_flag_with_azure_app_configuration_sample.py
+samples/feature_variant_sample.py
+samples/feature_variant_sample_with_telemetry.py
 samples/formatted_feature_flags.json
 samples/random_filter.py
 tests/test_default_feature_flags.py
@@ -38,4 +48,7 @@ tests/test_default_feature_flags_async.py
 tests/test_feature_manager.py
 tests/test_feature_manager_async.py
 tests/test_feature_manager_refresh.py
+tests/test_feature_variants.py
+tests/test_feature_variants_async.py
+tests/test_send_telemetry_appinsights.py
 tests/validation_tests/test_json_validations.py

featuremanagement-2.0.0b1/FeatureManagement.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[AzureMonitor]
+azure-monitor-events-extension<2.0.0

{featuremanagement-1.0.0/FeatureManagement.egg-info → featuremanagement-2.0.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: FeatureManagement
-Version: 1.0.0
+Version: 2.0.0b1
 Summary: A library for enabling/disabling features at runtime.
 Home-page: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/appconfiguration/feature-management
 Author: Microsoft Corporation
@@ -41,9 +41,8 @@ Classifier: License :: OSI Approved :: MIT License
 Requires-Python: >=3.6
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Provides-Extra: appinsights
-Requires-Dist: azure-monitor-opentelemetry<2.0.0,>=1.3.0; extra == "appinsights"
-Requires-Dist: azure-monitor-events-extension<2.0.0; extra == "appinsights"
+Provides-Extra: azuremonitor
+Requires-Dist: azure-monitor-events-extension<2.0.0; extra == "azuremonitor"
 
 # Microsoft Feature Management for Python
 
@@ -60,6 +59,7 @@ Feature management provides a way to develop and expose application functionalit
 ## Examples
 
 * [Python Application](https://github.com/microsoft/FeatureManagement-Python/blob/main/samples/feature_flag_sample.py)
+* [Python Application with Feature Variants](https://github.com/microsoft/FeatureManagement-Python/blob/main/samples/feature_variant_sample.py)
 * [Python Application with Azure App Configuration](https://github.com/microsoft/FeatureManagement-Python/blob/main/samples/feature_flag_with_azure_app_configuration_sample.py)
 * [Django Application](https://github.com/Azure/AppConfiguration/tree/main/examples/Python/python-django-webapp-sample)
 * [Flask Application](https://github.com/Azure/AppConfiguration/tree/main/examples/Python/python-flask-webapp-sample)

{featuremanagement-1.0.0 → featuremanagement-2.0.0b1}/README.md

@@ -13,6 +13,7 @@ Feature management provides a way to develop and expose application functionalit
 ## Examples
 
 * [Python Application](https://github.com/microsoft/FeatureManagement-Python/blob/main/samples/feature_flag_sample.py)
+* [Python Application with Feature Variants](https://github.com/microsoft/FeatureManagement-Python/blob/main/samples/feature_variant_sample.py)
 * [Python Application with Azure App Configuration](https://github.com/microsoft/FeatureManagement-Python/blob/main/samples/feature_flag_with_azure_app_configuration_sample.py)
 * [Django Application](https://github.com/Azure/AppConfiguration/tree/main/examples/Python/python-django-webapp-sample)
 * [Flask Application](https://github.com/Azure/AppConfiguration/tree/main/examples/Python/python-flask-webapp-sample)

{featuremanagement-1.0.0 → featuremanagement-2.0.0b1}/featuremanagement/__init__.py

@@ -6,7 +6,7 @@
 from ._featuremanager import FeatureManager
 from ._featurefilters import FeatureFilter
 from ._defaultfilters import TimeWindowFilter, TargetingFilter
-from ._models import TargetingContext
+from ._models import FeatureFlag, Variant, EvaluationEvent, VariantAssignmentReason, TargetingContext
 
 from ._version import VERSION
 
@@ -16,5 +16,9 @@ __all__ = [
     "TimeWindowFilter",
     "TargetingFilter",
     "FeatureFilter",
+    "FeatureFlag",
+    "Variant",
+    "EvaluationEvent",
+    "VariantAssignmentReason",
     "TargetingContext",
 ]

{featuremanagement-1.0.0 → featuremanagement-2.0.0b1}/featuremanagement/_defaultfilters.py

@@ -5,10 +5,9 @@
 # -------------------------------------------------------------------------
 import logging
 import hashlib
-
 from datetime import datetime, timezone
 from email.utils import parsedate_to_datetime
-
+from typing import cast, List, Mapping, Optional, Dict, Any
 from ._featurefilters import FeatureFilter
 
 FEATURE_FLAG_NAME_KEY = "feature_name"
@@ -45,7 +44,7 @@ class TimeWindowFilter(FeatureFilter):
     Feature Filter that determines if the current time is within the time window.
     """
 
-    def evaluate(self, context, **kwargs):
+    def evaluate(self, context: Mapping[Any, Any], **kwargs: Any) -> bool:
         """
         Determine if the feature flag is enabled for the given context.
 
@@ -75,7 +74,7 @@ class TargetingFilter(FeatureFilter):
     """
 
     @staticmethod
-    def _is_targeted(context_id, rollout_percentage):
+    def _is_targeted(context_id: str, rollout_percentage: int) -> bool:
         """Determine if the user is targeted for the given context"""
         # Always return true if rollout percentage is 100
         if rollout_percentage == 100:
@@ -87,7 +86,9 @@ class TargetingFilter(FeatureFilter):
         percentage = (context_marker / (2**32 - 1)) * 100
         return percentage < rollout_percentage
 
-    def _target_group(self, target_user, target_group, group, feature_flag_name):
+    def _target_group(
+        self, target_user: Optional[str], target_group: str, group: Mapping[str, Any], feature_flag_name: str
+    ) -> bool:
         group_rollout_percentage = group.get(ROLLOUT_PERCENTAGE_KEY, 0)
         if not target_user:
             target_user = ""
@@ -95,7 +96,7 @@ class TargetingFilter(FeatureFilter):
 
         return self._is_targeted(audience_context_id, group_rollout_percentage)
 
-    def evaluate(self, context, **kwargs):
+    def evaluate(self, context: Mapping[Any, Any], **kwargs: Any) -> bool:
         """
         Determine if the feature flag is enabled for the given context.
 
@@ -103,8 +104,11 @@ class TargetingFilter(FeatureFilter):
         :return: True if the user is targeted for the feature flag.
         :rtype: bool
         """
-        target_user = kwargs.get(TARGETED_USER_KEY, None)
-        target_groups = kwargs.get(TARGETED_GROUPS_KEY, [])
+        target_user: Optional[str] = cast(
+            str,
+            kwargs.get(TARGETED_USER_KEY, None),
+        )
+        target_groups: List[str] = cast(List[str], kwargs.get(TARGETED_GROUPS_KEY, []))
 
         if not target_user and not (target_groups and len(target_groups) > 0):
             logging.warning("%s: Name or Groups are required parameters", TargetingFilter.__name__)
@@ -152,11 +156,11 @@ class TargetingFilter(FeatureFilter):
         return self._is_targeted(context_id, default_rollout_percentage)
 
     @staticmethod
-    def _validate(groups, default_rollout_percentage):
+    def _validate(groups: List[Dict[str, Any]], default_rollout_percentage: int) -> None:
         # Validate the audience settings
         if default_rollout_percentage < 0 or default_rollout_percentage > 100:
             raise TargetingException("DefaultRolloutPercentage must be between 0 and 100")
 
         for group in groups:
-            if group.get(ROLLOUT_PERCENTAGE_KEY) < 0 or group.get(ROLLOUT_PERCENTAGE_KEY) > 100:
+            if group.get(ROLLOUT_PERCENTAGE_KEY, 0) < 0 or group.get(ROLLOUT_PERCENTAGE_KEY, 100) > 100:
                 raise TargetingException("RolloutPercentage must be between 0 and 100")

{featuremanagement-1.0.0 → featuremanagement-2.0.0b1}/featuremanagement/_featurefilters.py

@@ -4,6 +4,7 @@
 # license information.
 # -------------------------------------------------------------------------
 from abc import ABC, abstractmethod
+from typing import Mapping, Callable, Any, Optional
 
 
 class FeatureFilter(ABC):
@@ -11,8 +12,10 @@ class FeatureFilter(ABC):
     Parent class for all feature filters.
     """
 
+    _alias: Optional[str] = None
+
     @abstractmethod
-    def evaluate(self, context, **kwargs):
+    def evaluate(self, context: Mapping[Any, Any], **kwargs: Any) -> bool:
         """
         Determine if the feature flag is enabled for the given context.
 
@@ -20,28 +23,28 @@ class FeatureFilter(ABC):
         """
 
     @property
-    def name(self):
+    def name(self) -> str:
         """
         Get the name of the filter.
 
         :return: Name of the filter, or alias if it exists.
         :rtype: str
         """
-        if hasattr(self, "_alias"):
+        if hasattr(self, "_alias") and self._alias:
             return self._alias
         return self.__class__.__name__
 
     @staticmethod
-    def alias(alias):
+    def alias(alias: str) -> Callable[..., Any]:
         """
         Decorator to set the alias for the filter.
 
         :param str alias: Alias for the filter.
         :return: Decorator.
-        :rtype: callable
+        :rtype: Callable
         """
 
-        def wrapper(cls):
+        def wrapper(cls: "FeatureFilter") -> Any:
             cls._alias = alias  # pylint: disable=protected-access
             return cls
 

{featuremanagement-1.0.0 → featuremanagement-2.0.0b1}/featuremanagement/_featuremanager.py

@@ -4,106 +4,44 @@
 # license information.
 # -------------------------------------------------------------------------
 import logging
-from collections.abc import Mapping
-from typing import overload
+from typing import cast, overload, Any, Optional, Dict, Mapping, List
 from ._defaultfilters import TimeWindowFilter, TargetingFilter
 from ._featurefilters import FeatureFilter
-from ._models import FeatureFlag, EvaluationEvent, TargetingContext
-
-
-FEATURE_MANAGEMENT_KEY = "feature_management"
-FEATURE_FLAG_KEY = "feature_flags"
-
-PROVIDED_FEATURE_FILTERS = "feature_filters"
-FEATURE_FILTER_NAME = "name"
-REQUIREMENT_TYPE_ALL = "All"
-REQUIREMENT_TYPE_ANY = "Any"
-
-FEATURE_FILTER_PARAMETERS = "parameters"
-
-
-def _get_feature_flag(configuration, feature_flag_name):
-    """
-    Gets the FeatureFlag json from the configuration, if it exists it gets converted to a FeatureFlag object.
-
-    :param Mapping configuration: Configuration object.
-    :param str feature_flag_name: Name of the feature flag.
-    :return: FeatureFlag
-    :rtype: FeatureFlag
-    """
-    feature_management = configuration.get(FEATURE_MANAGEMENT_KEY)
-    if not feature_management or not isinstance(feature_management, Mapping):
-        return None
-    feature_flags = feature_management.get(FEATURE_FLAG_KEY)
-    if not feature_flags or not isinstance(feature_flags, list):
-        return None
-
-    for feature_flag in feature_flags:
-        if feature_flag.get("id") == feature_flag_name:
-            return FeatureFlag.convert_from_json(feature_flag)
-
-    return None
-
-
-def _list_feature_flag_names(configuration):
-    """
-    List of all feature flag names.
-
-    :param Mapping configuration: Configuration object.
-    :return: List of feature flag names.
-    """
-    feature_flag_names = []
-    feature_management = configuration.get(FEATURE_MANAGEMENT_KEY)
-    if not feature_management or not isinstance(feature_management, Mapping):
-        return []
-    feature_flags = feature_management.get(FEATURE_FLAG_KEY)
-    if not feature_flags or not isinstance(feature_flags, list):
-        return []
-
-    for feature_flag in feature_flags:
-        feature_flag_names.append(feature_flag.get("id"))
-
-    return feature_flag_names
-
-
-class FeatureManager:
+from ._models import EvaluationEvent, Variant, TargetingContext
+from ._featuremanagerbase import (
+    _get_feature_flag,
+    FeatureManagerBase,
+    PROVIDED_FEATURE_FILTERS,
+    FEATURE_MANAGEMENT_KEY,
+    REQUIREMENT_TYPE_ALL,
+    FEATURE_FILTER_NAME,
+)
+
+
+class FeatureManager(FeatureManagerBase):
     """
     Feature Manager that determines if a feature flag is enabled for the given context.
 
     :param Mapping configuration: Configuration object.
     :keyword list[FeatureFilter] feature_filters: Custom filters to be used for evaluating feature flags.
+    :keyword Callable[EvaluationEvent] on_feature_evaluated: Callback function to be called when a feature flag is
+    evaluated.
     """
 
-    def __init__(self, configuration, **kwargs):
-        self._filters = {}
-        if configuration is None or not isinstance(configuration, Mapping):
-            raise AttributeError("Configuration must be a non-empty dictionary")
-        self._configuration = configuration
-        self._cache = {}
-        self._copy = configuration.get(FEATURE_MANAGEMENT_KEY)
-        filters = [TimeWindowFilter(), TargetingFilter()] + kwargs.pop(PROVIDED_FEATURE_FILTERS, [])
+    def __init__(self, configuration: Mapping[str, Any], **kwargs: Any):
+        super().__init__(configuration, **kwargs)
+        self._filters: Dict[str, FeatureFilter] = {}
+        filters = [TimeWindowFilter(), TargetingFilter()] + cast(
+            List[FeatureFilter], kwargs.pop(PROVIDED_FEATURE_FILTERS, [])
+        )
 
         for feature_filter in filters:
             if not isinstance(feature_filter, FeatureFilter):
                 raise ValueError("Custom filter must be a subclass of FeatureFilter")
             self._filters[feature_filter.name] = feature_filter
 
-    def _build_targeting_context(self, args):
-        """
-        Builds a TargetingContext, either returns a provided context, takes the provided user_id to make a context, or
-        returns an empty context.
-
-        :param args: Arguments to build the TargetingContext.
-        :return: TargetingContext
-        """
-        if len(args) == 1 and isinstance(args[0], str):
-            return TargetingContext(user_id=args[0], groups=[])
-        if len(args) == 1 and isinstance(args[0], TargetingContext):
-            return args[0]
-        return TargetingContext()
-
-    @overload
-    def is_enabled(self, feature_flag_id, user_id, **kwargs):
+    @overload  # type: ignore
+    def is_enabled(self, feature_flag_id: str, user_id: str, **kwargs: Any) -> bool:
         """
         Determine if the feature flag is enabled for the given context.
 
@@ -113,7 +51,7 @@ class FeatureManager:
         :rtype: bool
         """
 
-    def is_enabled(self, feature_flag_id, *args, **kwargs):
+    def is_enabled(self, feature_flag_id: str, *args: Any, **kwargs: Any) -> bool:
         """
         Determine if the feature flag is enabled for the given context.
 
@@ -124,12 +62,57 @@ class FeatureManager:
         targeting_context = self._build_targeting_context(args)
 
         result = self._check_feature(feature_flag_id, targeting_context, **kwargs)
+        if (
+            self._on_feature_evaluated
+            and result.feature
+            and result.feature.telemetry.enabled
+            and callable(self._on_feature_evaluated)
+        ):
+            result.user = targeting_context.user_id
+            self._on_feature_evaluated(result)
         return result.enabled
 
-    def _check_feature_filters(self, feature_flag, targeting_context, **kwargs):
+    @overload  # type: ignore
+    def get_variant(self, feature_flag_id: str, user_id: str, **kwargs: Any) -> Optional[Variant]:
+        """
+        Determine the variant for the given context.
+
+        :param str feature_flag_id: Name of the feature flag.
+        :param str user_id: User identifier.
+        :return: return: Variant instance.
+        :rtype: Variant
+        """
+
+    def get_variant(self, feature_flag_id: str, *args: Any, **kwargs: Any) -> Optional[Variant]:
+        """
+        Determine the variant for the given context.
+
+        :param str feature_flag_id: Name of the feature flag
+        :keyword TargetingContext targeting_context: Targeting context.
+        :return: Variant instance.
+        :rtype: Variant
+        """
+        targeting_context = self._build_targeting_context(args)
+
+        result = self._check_feature(feature_flag_id, targeting_context, **kwargs)
+        if (
+            self._on_feature_evaluated
+            and result.feature
+            and result.feature.telemetry.enabled
+            and callable(self._on_feature_evaluated)
+        ):
+            result.user = targeting_context.user_id
+            self._on_feature_evaluated(result)
+        return result.variant
+
+    def _check_feature_filters(
+        self, evaluation_event: EvaluationEvent, targeting_context: TargetingContext, **kwargs: Any
+    ) -> None:
+        feature_flag = evaluation_event.feature
+        if not feature_flag:
+            return
         feature_conditions = feature_flag.conditions
         feature_filters = feature_conditions.client_filters
-        evaluation_event = EvaluationEvent(enabled=False)
 
         if len(feature_filters) == 0:
             # Feature flags without any filters return evaluate
@@ -152,9 +135,10 @@ class FeatureManager:
             elif self._filters[filter_name].evaluate(feature_filter, **kwargs):
                 evaluation_event.enabled = True
                 break
-        return evaluation_event
 
-    def _check_feature(self, feature_flag_id, targeting_context, **kwargs):
+    def _check_feature(
+        self, feature_flag_id: str, targeting_context: TargetingContext, **kwargs: Any
+    ) -> EvaluationEvent:
         """
         Determine if the feature flag is enabled for the given context.
 
@@ -172,19 +156,25 @@ class FeatureManager:
         else:
             feature_flag = self._cache.get(feature_flag_id)
 
+        evaluation_event = EvaluationEvent(feature_flag)
         if not feature_flag:
             logging.warning("Feature flag %s not found", feature_flag_id)
             # Unknown feature flags are disabled by default
-            return EvaluationEvent(enabled=False)
+            return evaluation_event
 
         if not feature_flag.enabled:
             # Feature flags that are disabled are always disabled
-            return EvaluationEvent(enabled=False)
+            FeatureManager._check_default_disabled_variant(evaluation_event)
+            if feature_flag.allocation:
+                variant_name = feature_flag.allocation.default_when_disabled
+                evaluation_event.variant = self._variant_name_to_variant(feature_flag, variant_name)
+            evaluation_event.feature = feature_flag
 
-        return self._check_feature_filters(feature_flag, targeting_context, **kwargs)
+            # If a feature flag is disabled and override can't enable it
+            evaluation_event.enabled = False
+            return evaluation_event
 
-    def list_feature_flag_names(self):
-        """
-        List of all feature flag names.
-        """
-        return _list_feature_flag_names(self._configuration)
+        self._check_feature_filters(evaluation_event, targeting_context, **kwargs)
+
+        self._assign_allocation(evaluation_event, targeting_context)
+        return evaluation_event