flagsmith-flag-engine 6.0.2__tar.gz → 6.1.0__tar.gz

{flagsmith_flag_engine-6.0.2/flagsmith_flag_engine.egg-info → flagsmith_flag_engine-6.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith-flag-engine
-Version: 6.0.2
+Version: 6.1.0
 Summary: Flag engine for the Flagsmith API.
 Home-page: https://github.com/Flagsmith/flagsmith-engine
 Author: Flagsmith
@@ -8,9 +8,11 @@ Author-email: support@flagsmith.com
 License: BSD3
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Programming Language :: Python :: 3
-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 :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: pydantic<3,>=2.3.0

flagsmith_flag_engine-6.1.0/flag_engine/context/mappers.py

@@ -0,0 +1,253 @@
+import json
+import typing
+from collections import defaultdict
+
+from flag_engine.context.types import (
+    EvaluationContext,
+    FeatureContext,
+    SegmentContext,
+    SegmentRule,
+)
+from flag_engine.environments.models import EnvironmentModel
+from flag_engine.features.models import (
+    FeatureModel,
+    FeatureStateModel,
+    MultivariateFeatureStateValueModel,
+)
+from flag_engine.identities.models import IdentityModel
+from flag_engine.identities.traits.models import TraitModel
+from flag_engine.result.types import FlagResult
+from flag_engine.segments.models import SegmentRuleModel
+
+OverrideKey = typing.Tuple[
+    str,
+    str,
+    bool,
+    typing.Any,
+]
+OverridesKey = typing.Tuple[OverrideKey, ...]
+
+
+def map_environment_identity_to_context(
+    environment: EnvironmentModel,
+    identity: typing.Optional[IdentityModel],
+    override_traits: typing.Optional[typing.List[TraitModel]],
+) -> EvaluationContext:
+    """
+    Map an EnvironmentModel and IdentityModel to an EvaluationContext.
+
+    :param environment: The environment model object.
+    :param identity: The identity model object.
+    :param override_traits: A list of TraitModel objects, to be used in place of `identity.identity_traits` if provided.
+    :return: An EvaluationContext containing the environment and identity.
+    """
+    features = _map_feature_states_to_feature_contexts(environment.feature_states)
+    segments: typing.Dict[str, SegmentContext] = {}
+    for segment in environment.project.segments:
+        segment_ctx_data: SegmentContext = {
+            "key": str(segment.id),
+            "name": segment.name,
+            "rules": _map_segment_rules_to_segment_context_rules(segment.rules),
+        }
+        if segment_feature_states := segment.feature_states:
+            segment_ctx_data["overrides"] = list(
+                _map_feature_states_to_feature_contexts(segment_feature_states).values()
+            )
+        segments[str(segment.id)] = segment_ctx_data
+    identity_overrides = environment.identity_overrides + [identity] if identity else []
+    segments.update(_map_identity_overrides_to_segment_contexts(identity_overrides))
+    return {
+        "environment": {
+            "key": environment.api_key,
+            "name": environment.name or "",
+        },
+        "identity": (
+            {
+                "identifier": identity.identifier,
+                "key": str(identity.django_id or identity.composite_key),
+                "traits": {
+                    trait.trait_key: trait.trait_value
+                    for trait in (
+                        override_traits
+                        if override_traits is not None
+                        else identity.identity_traits
+                    )
+                },
+            }
+            if identity
+            else None
+        ),
+        "features": features,
+        "segments": segments,
+    }
+
+
+def _map_identity_overrides_to_segment_contexts(
+    identity_overrides: typing.List[IdentityModel],
+) -> typing.Dict[str, SegmentContext]:
+    """
+    Map identity overrides to segment contexts.
+
+    :param identity_overrides: A list of IdentityModel objects.
+    :return: A dictionary mapping segment ids to SegmentContext objects.
+    """
+    features_to_identifiers: typing.Dict[
+        OverridesKey,
+        typing.List[str],
+    ] = defaultdict(list)
+    for identity_override in identity_overrides:
+        identity_features: typing.List[FeatureStateModel] = (
+            identity_override.identity_features
+        )
+        if not identity_features:
+            continue
+        overrides_key = tuple(
+            (
+                str(feature_state.feature.id),
+                feature_state.feature.name,
+                feature_state.enabled,
+                feature_state.feature_state_value,
+            )
+            for feature_state in sorted(identity_features, key=_get_name)
+        )
+        features_to_identifiers[overrides_key].append(identity_override.identifier)
+    segment_contexts: typing.Dict[str, SegmentContext] = {}
+    for overrides_key, identifiers in features_to_identifiers.items():
+        # Create a segment context for each unique set of overrides
+        # Generate a unique key to avoid collisions
+        segment_key = str(hash(overrides_key))
+        segment_contexts[segment_key] = SegmentContext(
+            key="",  # Identity override segments never use % Split operator
+            name="identity_overrides",
+            rules=[
+                {
+                    "type": "ALL",
+                    "conditions": [
+                        {
+                            "property": "$.identity.identifier",
+                            "operator": "IN",
+                            "value": json.dumps(identifiers),
+                        }
+                    ],
+                }
+            ],
+            overrides=[
+                {
+                    "key": "",  # Identity overrides never carry multivariate options
+                    "feature_key": feature_key,
+                    "name": feature_name,
+                    "enabled": feature_enabled,
+                    "value": feature_value,
+                    "priority": float("-inf"),  # Highest possible priority
+                }
+                for feature_key, feature_name, feature_enabled, feature_value in overrides_key
+            ],
+        )
+    return segment_contexts
+
+
+def _map_feature_states_to_feature_contexts(
+    feature_states: typing.List[FeatureStateModel],
+) -> typing.Dict[str, FeatureContext]:
+    """
+    Map feature states to feature contexts.
+
+    :param feature_states: A list of FeatureStateModel objects.
+    :return: A dictionary mapping feature names to their contexts.
+    """
+    features: typing.Dict[str, FeatureContext] = {}
+    for feature_state in feature_states:
+        feature_context: FeatureContext = {
+            "key": str(feature_state.django_id or feature_state.featurestate_uuid),
+            "feature_key": str(feature_state.feature.id),
+            "name": feature_state.feature.name,
+            "enabled": feature_state.enabled,
+            "value": feature_state.feature_state_value,
+        }
+        multivariate_feature_state_values: typing.List[
+            MultivariateFeatureStateValueModel
+        ]
+        if (
+            multivariate_feature_state_values := feature_state.multivariate_feature_state_values
+        ):
+            feature_context["variants"] = [
+                {
+                    "value": multivariate_feature_state_value.multivariate_feature_option.value,
+                    "weight": multivariate_feature_state_value.percentage_allocation,
+                }
+                for multivariate_feature_state_value in sorted(
+                    multivariate_feature_state_values,
+                    key=_get_multivariate_feature_state_value_id,
+                )
+            ]
+        if feature_segment := feature_state.feature_segment:
+            if (priority := feature_segment.priority) is not None:
+                feature_context["priority"] = priority
+        features[feature_state.feature.name] = feature_context
+    return features
+
+
+def _map_segment_rules_to_segment_context_rules(
+    rules: typing.List[SegmentRuleModel],
+) -> typing.List[SegmentRule]:
+    """
+    Map segment rules to segment rules for the evaluation context.
+
+    :param rules: A list of SegmentRuleModel objects.
+    :return: A list of SegmentRule objects.
+    """
+    return [
+        {
+            "type": rule.type,
+            "conditions": [
+                {
+                    "property": condition.property_ or "",
+                    "operator": condition.operator,
+                    "value": condition.value or "",
+                }
+                for condition in rule.conditions
+            ],
+            "rules": _map_segment_rules_to_segment_context_rules(rule.rules),
+        }
+        for rule in rules
+    ]
+
+
+def map_flag_results_to_feature_states(
+    flag_results: typing.List[FlagResult],
+) -> typing.List[FeatureStateModel]:
+    """
+    Map flag results to feature states.
+
+    :param flag_results: A list of FlagResult objects.
+    :return: A list of FeatureStateModel objects.
+    """
+    return [
+        FeatureStateModel(
+            feature=FeatureModel(
+                id=flag_result["feature_key"],
+                name=flag_result["name"],
+                type=(
+                    "MULTIVARIATE"
+                    if flag_result.get("reason", "").startswith("SPLIT")
+                    else "STANDARD"
+                ),
+            ),
+            enabled=flag_result["enabled"],
+            feature_state_value=flag_result["value"],
+        )
+        for flag_result in flag_results
+    ]
+
+
+def _get_multivariate_feature_state_value_id(
+    multivariate_feature_state_value: MultivariateFeatureStateValueModel,
+) -> int:
+    return (
+        multivariate_feature_state_value.id
+        or multivariate_feature_state_value.mv_fs_value_uuid.int
+    )
+
+
+def _get_name(feature_state: FeatureStateModel) -> str:
+    return feature_state.feature.name

flagsmith_flag_engine-6.1.0/flag_engine/context/types.py

@@ -0,0 +1,63 @@
+# generated by datamodel-codegen:
+#   filename:  https://raw.githubusercontent.com/Flagsmith/flagsmith/chore/features-contexts-in-eval-context-schema/sdk/evaluation-context.json  # noqa: E501
+#   timestamp: 2025-08-11T18:17:29+00:00
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TypedDict, Union
+
+from typing_extensions import NotRequired
+
+from flag_engine.segments.types import ConditionOperator, RuleType
+
+
+class EnvironmentContext(TypedDict):
+    key: str
+    name: str
+
+
+class FeatureValue(TypedDict):
+    value: Any
+    weight: float
+
+
+class IdentityContext(TypedDict):
+    identifier: str
+    key: str
+    traits: NotRequired[Dict[str, Optional[Union[str, float, bool]]]]
+
+
+class SegmentCondition(TypedDict):
+    property: NotRequired[str]
+    operator: ConditionOperator
+    value: str
+
+
+class SegmentRule(TypedDict):
+    type: RuleType
+    conditions: NotRequired[List[SegmentCondition]]
+    rules: NotRequired[List[SegmentRule]]
+
+
+class FeatureContext(TypedDict):
+    key: str
+    feature_key: str
+    name: str
+    enabled: bool
+    value: Any
+    variants: NotRequired[List[FeatureValue]]
+    priority: NotRequired[float]
+
+
+class SegmentContext(TypedDict):
+    key: str
+    name: str
+    rules: List[SegmentRule]
+    overrides: NotRequired[List[FeatureContext]]
+
+
+class EvaluationContext(TypedDict):
+    environment: EnvironmentContext
+    identity: NotRequired[Optional[IdentityContext]]
+    segments: NotRequired[Dict[str, SegmentContext]]
+    features: NotRequired[Dict[str, FeatureContext]]

{flagsmith_flag_engine-6.0.2 → flagsmith_flag_engine-6.1.0}/flag_engine/engine.py

@@ -1,14 +1,25 @@
 import typing
+import warnings
 
-from flag_engine.context.mappers import map_environment_identity_to_context
-from flag_engine.context.types import EvaluationContext
+from flag_engine.context.mappers import (
+    map_environment_identity_to_context,
+    map_flag_results_to_feature_states,
+)
 from flag_engine.environments.models import EnvironmentModel
-from flag_engine.features.models import FeatureModel, FeatureStateModel
+from flag_engine.features.models import FeatureStateModel
 from flag_engine.identities.models import IdentityModel
 from flag_engine.identities.traits.models import TraitModel
-from flag_engine.segments.evaluator import get_context_segments
+from flag_engine.segments.evaluator import get_evaluation_result
 from flag_engine.utils.exceptions import FeatureStateNotFound
 
+__all__ = (
+    "get_environment_feature_states",
+    "get_environment_feature_state",
+    "get_identity_feature_states",
+    "get_identity_feature_state",
+    "get_evaluation_result",
+)
+
 
 def get_environment_feature_states(
     environment: EnvironmentModel,
@@ -18,6 +29,10 @@ def get_environment_feature_states(
 
     :param environment: the environment model object
     """
+    warnings.warn(
+        "`get_environment_feature_states` is deprecated, use `get_evaluation_result` instead.",
+        DeprecationWarning,
+    )
     if environment.get_hide_disabled_flags():
         return [fs for fs in environment.feature_states if fs.enabled]
     return environment.feature_states
@@ -32,13 +47,16 @@ def get_environment_feature_state(
     :param environment: the environment model object
     :param feature_name: the name of the feature to get the feature state for
     """
-    try:
-        return next(
-            filter(lambda f: f.feature.name == feature_name, environment.feature_states)
-        )
+    warnings.warn(
+        "`get_environment_feature_state` is deprecated, use `get_evaluation_result` instead.",
+        DeprecationWarning,
+    )
 
-    except StopIteration:
-        raise FeatureStateNotFound()
+    for feature_state in environment.feature_states:
+        if feature_state.feature.name == feature_name:
+            return feature_state
+
+    raise FeatureStateNotFound()
 
 
 def get_identity_feature_states(
@@ -55,19 +73,20 @@ def get_identity_feature_states(
     :return: list of feature state models based on the environment, any matching
         segments and any specific identity overrides
     """
+    warnings.warn(
+        "`get_identity_feature_states` is deprecated, use `get_evaluation_result` instead.",
+        DeprecationWarning,
+    )
     context = map_environment_identity_to_context(
         environment=environment,
         identity=identity,
         override_traits=override_traits,
     )
 
-    feature_states = list(
-        _get_identity_feature_states_dict(
-            environment=environment,
-            identity=identity,
-            context=context,
-        ).values()
-    )
+    result = get_evaluation_result(context)
+
+    feature_states = map_flag_results_to_feature_states(result["flags"])
+
     if environment.get_hide_disabled_flags():
         return [fs for fs in feature_states if fs.enabled]
     return feature_states
@@ -89,58 +108,20 @@ def get_identity_feature_state(
     :return: feature state model based on the environment, any matching
         segments and any specific identity overrides
     """
+    warnings.warn(
+        "`get_identity_feature_state` is deprecated, use `get_evaluation_result` instead.",
+        DeprecationWarning,
+    )
     context = map_environment_identity_to_context(
         environment=environment,
         identity=identity,
         override_traits=override_traits,
     )
 
-    feature_states = _get_identity_feature_states_dict(
-        environment=environment,
-        identity=identity,
-        context=context,
-    )
-    matching_feature = next(
-        filter(lambda feature: feature.name == feature_name, feature_states.keys()),
-        None,
-    )
-
-    if not matching_feature:
-        raise FeatureStateNotFound()
-
-    return feature_states[matching_feature]
+    result = get_evaluation_result(context)
 
+    for feature_state in map_flag_results_to_feature_states(result["flags"]):
+        if feature_state.feature.name == feature_name:
+            return feature_state
 
-def _get_identity_feature_states_dict(
-    environment: EnvironmentModel,
-    identity: IdentityModel,
-    context: EvaluationContext,
-) -> typing.Dict[FeatureModel, FeatureStateModel]:
-    # Get feature states from the environment
-    feature_states_by_feature = {fs.feature: fs for fs in environment.feature_states}
-
-    # Override with any feature states defined by matching segments
-    for context_segment in get_context_segments(
-        context=context,
-        segments=environment.project.segments,
-    ):
-        for segment_feature_state in context_segment.feature_states:
-            if (
-                feature_state := feature_states_by_feature.get(
-                    segment_feature := segment_feature_state.feature
-                )
-            ) and feature_state.is_higher_segment_priority(segment_feature_state):
-                continue
-            feature_states_by_feature[segment_feature] = segment_feature_state
-
-    # Override with any feature states defined directly the identity
-    feature_states_by_feature.update(
-        {
-            identity_feature: identity_feature_state
-            for identity_feature_state in identity.identity_features
-            if (identity_feature := identity_feature_state.feature)
-            in feature_states_by_feature
-        }
-    )
-
-    return feature_states_by_feature
+    raise FeatureStateNotFound()

{flagsmith_flag_engine-6.0.2 → flagsmith_flag_engine-6.1.0}/flag_engine/features/models.py

@@ -1,14 +1,13 @@
-import math
 import typing
 import uuid
+import warnings
 
-from annotated_types import Ge, Le, SupportsLt
+from annotated_types import Ge, Le
 from pydantic import UUID4, BaseModel, Field, model_validator
 from pydantic_collections import BaseCollectionModel
 from typing_extensions import Annotated
 
 from flag_engine.utils.exceptions import InvalidPercentageAllocation
-from flag_engine.utils.hashing import get_hashed_percentage_for_object_ids
 
 
 class FeatureModel(BaseModel):
@@ -19,9 +18,6 @@ class FeatureModel(BaseModel):
     def __eq__(self, other: object) -> bool:
         return isinstance(other, FeatureModel) and self.id == other.id
 
-    def __hash__(self) -> int:
-        return hash(self.id)
-
 
 class MultivariateFeatureOptionModel(BaseModel):
     value: typing.Any
@@ -88,72 +84,15 @@ class FeatureStateModel(BaseModel, validate_assignment=True):
 
     def get_value(self, identity_id: typing.Union[None, int, str] = None) -> typing.Any:
         """
-        Get the value of the feature state.
+        DEPRECATED: Get the value of the feature state.
+        Use the `feature_state_value` field directly instead.
 
         :param identity_id: a unique identifier for the identity, can be either a
             numeric id or a string but must be unique for the identity.
         :return: the value of the feature state.
         """
-        if identity_id and len(self.multivariate_feature_state_values) > 0:
-            return self._get_multivariate_value(identity_id)
-        return self.feature_state_value
-
-    def is_higher_segment_priority(self, other: "FeatureStateModel") -> bool:
-        """
-        Returns `True` if `self` is higher segment priority than `other`
-        (i.e. has lower value for feature_segment.priority)
-
-        NOTE:
-            A segment will be considered higher priority only if:
-            1. `other` does not have a feature segment(i.e: it is an environment feature state or it's a
-            feature state with feature segment but from an old document that does not have `feature_segment.priority`)
-            but `self` does.
-
-            2. `other` have a feature segment with high priority
-
-        """
-
-        if other_feature_segment := other.feature_segment:
-            if (
-                other_feature_segment_priority := other_feature_segment.priority
-            ) is not None:
-                return (
-                    getattr(
-                        self.feature_segment,
-                        "priority",
-                        math.inf,
-                    )
-                    < other_feature_segment_priority
-                )
-        return False
-
-    def _get_multivariate_value(
-        self, identity_id: typing.Union[int, str]
-    ) -> typing.Any:
-        percentage_value = get_hashed_percentage_for_object_ids(
-            [self.django_id or self.featurestate_uuid, identity_id]
+        warnings.warn(
+            "get_value is deprecated, use feature_state_value directly.",
+            DeprecationWarning,
         )
-
-        # Iterate over the mv options in order of id (so we get the same value each
-        # time) to determine the correct value to return to the identity based on
-        # the percentage allocations of the multivariate options. This gives us a
-        # way to ensure that the same value is returned every time we use the same
-        # percentage value.
-        start_percentage = 0.0
-
-        def _mv_fs_sort_key(mv_value: MultivariateFeatureStateValueModel) -> SupportsLt:
-            return mv_value.id or mv_value.mv_fs_value_uuid
-
-        for mv_value in sorted(
-            self.multivariate_feature_state_values,
-            key=_mv_fs_sort_key,
-        ):
-            limit = mv_value.percentage_allocation + start_percentage
-            if start_percentage <= percentage_value < limit:
-                return mv_value.multivariate_feature_option.value
-
-            start_percentage = limit
-
-        # default to return the control value if no MV values found, although this
-        # should never happen
         return self.feature_state_value

flagsmith_flag_engine-6.1.0/flag_engine/result/types.py

@@ -0,0 +1,30 @@
+# generated by datamodel-codegen:
+#   filename:  result.json
+#   timestamp: 2025-08-11T11:47:46+00:00
+
+from __future__ import annotations
+
+from typing import Any, List, Optional, TypedDict
+
+from typing_extensions import NotRequired
+
+from flag_engine.context.types import EvaluationContext
+
+
+class FlagResult(TypedDict):
+    name: str
+    feature_key: str
+    enabled: bool
+    value: NotRequired[Optional[Any]]
+    reason: NotRequired[str]
+
+
+class SegmentResult(TypedDict):
+    key: str
+    name: str
+
+
+class EvaluationResult(TypedDict):
+    context: EvaluationContext
+    flags: List[FlagResult]
+    segments: List[SegmentResult]

{flagsmith_flag_engine-6.0.2 → flagsmith_flag_engine-6.1.0}/flag_engine/segments/constants.py

@@ -20,3 +20,6 @@ MODULO: ConditionOperator = "MODULO"
 IS_SET: ConditionOperator = "IS_SET"
 IS_NOT_SET: ConditionOperator = "IS_NOT_SET"
 IN: ConditionOperator = "IN"
+
+# Lowest possible priority for segment overrides
+DEFAULT_PRIORITY = float("inf")