flagsmith-flag-engine 6.0.1__py3-none-any.whl

flag_engine/context/mappers.py

@@ -0,0 +1,39 @@
+import typing
+
+from flag_engine.context.types import EvaluationContext
+from flag_engine.environments.models import EnvironmentModel
+from flag_engine.identities.models import IdentityModel
+from flag_engine.identities.traits.models import TraitModel
+
+
+def map_environment_identity_to_context(
+    environment: EnvironmentModel,
+    identity: IdentityModel,
+    override_traits: typing.Optional[typing.List[TraitModel]],
+) -> EvaluationContext:
+    """
+    Maps 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.
+    """
+    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
+                )
+            },
+        },
+    }

flag_engine/context/types.py

@@ -0,0 +1,28 @@
+# generated by datamodel-codegen:
+#   filename:  https://raw.githubusercontent.com/Flagsmith/flagsmith/chore/update-evaluation-context/sdk/evaluation-context.json  # noqa: E501
+#   timestamp: 2025-07-16T10:39:10+00:00
+
+from __future__ import annotations
+
+from typing import Dict, Optional, TypedDict
+
+from typing_extensions import NotRequired
+
+from flag_engine.identities.traits.types import ContextValue
+from flag_engine.utils.types import SupportsStr
+
+
+class EnvironmentContext(TypedDict):
+    key: str
+    name: str
+
+
+class IdentityContext(TypedDict):
+    identifier: str
+    key: SupportsStr
+    traits: NotRequired[Dict[str, ContextValue]]
+
+
+class EvaluationContext(TypedDict):
+    environment: EnvironmentContext
+    identity: NotRequired[Optional[IdentityContext]]

flag_engine/engine.py

@@ -0,0 +1,146 @@
+import typing
+
+from flag_engine.context.mappers import map_environment_identity_to_context
+from flag_engine.context.types import EvaluationContext
+from flag_engine.environments.models import EnvironmentModel
+from flag_engine.features.models import FeatureModel, 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.utils.exceptions import FeatureStateNotFound
+
+
+def get_environment_feature_states(
+    environment: EnvironmentModel,
+) -> typing.List[FeatureStateModel]:
+    """
+    Get a list of feature states for a given environment
+
+    :param environment: the environment model object
+    """
+    if environment.get_hide_disabled_flags():
+        return [fs for fs in environment.feature_states if fs.enabled]
+    return environment.feature_states
+
+
+def get_environment_feature_state(
+    environment: EnvironmentModel, feature_name: str
+) -> FeatureStateModel:
+    """
+    Get a specific feature state for a given feature_name in a given environment
+
+    :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)
+        )
+
+    except StopIteration:
+        raise FeatureStateNotFound()
+
+
+def get_identity_feature_states(
+    environment: EnvironmentModel,
+    identity: IdentityModel,
+    override_traits: typing.Optional[typing.List[TraitModel]] = None,
+) -> typing.List[FeatureStateModel]:
+    """
+    Get a list of feature states for a given identity in a given environment.
+
+    :param environment: the environment model object the identity belongs to
+    :param identity: the identity model object to get the feature state for
+    :param override_traits: optionally override the traits on the identity model
+    :return: list of feature state models based on the environment, any matching
+        segments and any specific identity overrides
+    """
+    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()
+    )
+    if environment.get_hide_disabled_flags():
+        return [fs for fs in feature_states if fs.enabled]
+    return feature_states
+
+
+def get_identity_feature_state(
+    environment: EnvironmentModel,
+    identity: IdentityModel,
+    feature_name: str,
+    override_traits: typing.Optional[typing.List[TraitModel]] = None,
+) -> FeatureStateModel:
+    """
+    Get a specific feature state for a given identity in a given environment.
+
+    :param environment: the environment model object the identity belongs to
+    :param identity: the identity model object to get the feature state for
+    :param feature_name: the name of the feature to get the feature state for
+    :param override_traits: optionally override the traits on the identity model
+    :return: feature state model based on the environment, any matching
+        segments and any specific identity overrides
+    """
+    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]
+
+
+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

flag_engine/environments/integrations/models.py

@@ -0,0 +1,9 @@
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class IntegrationModel(BaseModel):
+    api_key: Optional[str] = None
+    base_url: Optional[str] = None
+    entity_selector: Optional[str] = None

flag_engine/environments/models.py

@@ -0,0 +1,95 @@
+import typing
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from flag_engine.environments.integrations.models import IntegrationModel
+from flag_engine.features.models import FeatureStateModel
+from flag_engine.identities.models import IdentityModel
+from flag_engine.projects.models import ProjectModel
+from flag_engine.utils.datetime import utcnow_with_tz
+
+
+class EnvironmentAPIKeyModel(BaseModel):
+    id: int
+    key: str
+    created_at: datetime
+    name: str
+    client_api_key: str
+    expires_at: typing.Optional[datetime] = None
+    active: bool = True
+
+    @property
+    def is_valid(self) -> bool:
+        return self.active and (
+            not self.expires_at or self.expires_at > utcnow_with_tz()
+        )
+
+
+class WebhookModel(BaseModel):
+    url: str
+    secret: str
+
+
+class EnvironmentModel(BaseModel):
+    id: int
+    api_key: str
+    project: ProjectModel
+    feature_states: typing.List[FeatureStateModel] = Field(default_factory=list)
+    identity_overrides: typing.List[IdentityModel] = Field(default_factory=list)
+
+    name: typing.Optional[str] = None
+    allow_client_traits: bool = True
+    updated_at: datetime = Field(default_factory=utcnow_with_tz)
+    hide_sensitive_data: bool = False
+    hide_disabled_flags: typing.Optional[bool] = None
+    use_identity_composite_key_for_hashing: bool = False
+    use_identity_overrides_in_local_eval: bool = False
+
+    amplitude_config: typing.Optional[IntegrationModel] = None
+    dynatrace_config: typing.Optional[IntegrationModel] = None
+    heap_config: typing.Optional[IntegrationModel] = None
+    mixpanel_config: typing.Optional[IntegrationModel] = None
+    rudderstack_config: typing.Optional[IntegrationModel] = None
+    segment_config: typing.Optional[IntegrationModel] = None
+
+    webhook_config: typing.Optional[WebhookModel] = None
+
+    _INTEGRATION_ATTRS = [
+        "amplitude_config",
+        "heap_config",
+        "mixpanel_config",
+        "rudderstack_config",
+        "segment_config",
+    ]
+
+    @property
+    def integrations_data(self) -> typing.Dict[str, typing.Dict[str, str]]:
+        """
+        Return a dictionary representation of all integration config objects.
+
+            e.g.
+            {
+                "mixpanel_config": {"base_url": None, "api_key": "some-key"},
+                "segment_config": {
+                    "base_url": "https://api.segment.com",
+                    "api_key": "some-key",
+                }
+            }
+        """
+
+        integrations_data = {}
+        for integration_attr in self._INTEGRATION_ATTRS:
+            integration_config: typing.Optional[IntegrationModel]
+            if integration_config := getattr(self, integration_attr, None):
+                integrations_data[integration_attr] = {
+                    "base_url": integration_config.base_url,
+                    "api_key": integration_config.api_key,
+                    "entity_selector": integration_config.entity_selector,
+                }
+        return integrations_data
+
+    def get_hide_disabled_flags(self) -> bool:
+        if self.hide_disabled_flags is not None:
+            return self.hide_disabled_flags
+        return self.project.hide_disabled_flags

flag_engine/features/constants.py

@@ -0,0 +1,3 @@
+# Feature Types
+STANDARD = "STANDARD"
+MULTIVARIATE = "MULTIVARIATE"

flag_engine/features/models.py

@@ -0,0 +1,159 @@
+import math
+import typing
+import uuid
+
+from annotated_types import Ge, Le, SupportsLt
+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):
+    id: int
+    name: str
+    type: str
+
+    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
+    id: typing.Optional[int] = None
+
+
+class MultivariateFeatureStateValueModel(BaseModel):
+    multivariate_feature_option: MultivariateFeatureOptionModel
+    percentage_allocation: Annotated[float, Ge(0), Le(100)]
+    id: typing.Optional[int] = None
+    mv_fs_value_uuid: UUID4 = Field(default_factory=uuid.uuid4)
+
+
+class FeatureSegmentModel(BaseModel):
+    priority: typing.Optional[int] = None
+
+
+class MultivariateFeatureStateValueList(
+    BaseCollectionModel[MultivariateFeatureStateValueModel]  # type: ignore[misc,no-any-unimported]
+):
+    @staticmethod
+    def _ensure_correct_percentage_allocations(
+        value: typing.List[MultivariateFeatureStateValueModel],
+    ) -> typing.List[MultivariateFeatureStateValueModel]:
+        if (
+            sum(
+                multivariate_feature_state.percentage_allocation
+                for multivariate_feature_state in value
+            )
+            > 100
+        ):
+            raise InvalidPercentageAllocation(
+                "Total percentage allocation for feature must be less or equal to 100 percent"
+            )
+        return value
+
+    percentage_allocations_model_validator = model_validator(mode="after")(
+        _ensure_correct_percentage_allocations
+    )
+
+    def append(
+        self,
+        multivariate_feature_state_value: MultivariateFeatureStateValueModel,
+    ) -> None:
+        self._ensure_correct_percentage_allocations(
+            [*self, multivariate_feature_state_value],
+        )
+        super().append(multivariate_feature_state_value)
+
+
+class FeatureStateModel(BaseModel, validate_assignment=True):
+    feature: FeatureModel
+    enabled: bool
+    django_id: typing.Optional[int] = None
+    feature_segment: typing.Optional[FeatureSegmentModel] = None
+    featurestate_uuid: UUID4 = Field(default_factory=uuid.uuid4)
+    feature_state_value: typing.Any = None
+    multivariate_feature_state_values: MultivariateFeatureStateValueList = Field(
+        default_factory=MultivariateFeatureStateValueList
+    )
+
+    def set_value(self, value: typing.Any) -> None:
+        self.feature_state_value = value
+
+    def get_value(self, identity_id: typing.Union[None, int, str] = None) -> typing.Any:
+        """
+        Get the value of the feature state.
+
+        :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]
+        )
+
+        # 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

flag_engine/identities/models.py

@@ -0,0 +1,93 @@
+import datetime
+import typing
+import uuid
+
+from pydantic import UUID4, BaseModel, Field, computed_field, model_validator
+from pydantic_collections import BaseCollectionModel
+
+from flag_engine.features.models import FeatureStateModel
+from flag_engine.identities.traits.models import TraitModel
+from flag_engine.utils.datetime import utcnow_with_tz
+from flag_engine.utils.exceptions import DuplicateFeatureState
+
+
+class IdentityFeaturesList(BaseCollectionModel[FeatureStateModel]):  # type: ignore[misc,no-any-unimported]
+    @staticmethod
+    def _ensure_unique_feature_ids(
+        value: typing.Sequence[FeatureStateModel],
+    ) -> None:
+        for i, feature_state in enumerate(value, start=1):
+            if feature_state.feature.id in [
+                feature_state.feature.id for feature_state in value[i:]
+            ]:
+                raise DuplicateFeatureState(
+                    f"Feature state for feature id={feature_state.feature.id} already exists"
+                )
+
+    @model_validator(mode="after")
+    def ensure_unique_feature_ids(self) -> "IdentityFeaturesList":
+        self._ensure_unique_feature_ids(self.root)
+        return self
+
+    def append(self, feature_state: "FeatureStateModel") -> None:
+        self._ensure_unique_feature_ids([*self, feature_state])
+        super().append(feature_state)
+
+
+class IdentityModel(BaseModel):
+    identifier: str
+    environment_api_key: str
+    created_date: datetime.datetime = Field(default_factory=utcnow_with_tz)
+    identity_features: IdentityFeaturesList = Field(
+        default_factory=IdentityFeaturesList
+    )
+    identity_traits: typing.List[TraitModel] = Field(default_factory=list)
+    identity_uuid: UUID4 = Field(default_factory=uuid.uuid4)
+    django_id: typing.Optional[int] = None
+
+    dashboard_alias: typing.Optional[str] = None
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def composite_key(self) -> str:
+        return self.generate_composite_key(self.environment_api_key, self.identifier)
+
+    @staticmethod
+    def generate_composite_key(env_key: str, identifier: str) -> str:
+        return f"{env_key}_{identifier}"
+
+    def get_hash_key(self, use_identity_composite_key_for_hashing: bool) -> str:
+        return (
+            self.composite_key
+            if use_identity_composite_key_for_hashing
+            else self.identifier
+        )
+
+    def update_traits(
+        self, traits: typing.List[TraitModel]
+    ) -> typing.Tuple[typing.List[TraitModel], bool]:
+        existing_traits = {trait.trait_key: trait for trait in self.identity_traits}
+        traits_changed = False
+
+        for trait in traits:
+            existing_trait = existing_traits.get(trait.trait_key)
+
+            if trait.trait_value is None and existing_trait:
+                existing_traits.pop(trait.trait_key)
+                traits_changed = True
+
+            elif getattr(existing_trait, "trait_value", None) != trait.trait_value:
+                existing_traits[trait.trait_key] = trait
+                traits_changed = True
+
+        self.identity_traits = list(existing_traits.values())
+        return self.identity_traits, traits_changed
+
+    def prune_features(self, valid_feature_names: typing.List[str]) -> None:
+        self.identity_features = IdentityFeaturesList(
+            [
+                fs
+                for fs in self.identity_features
+                if fs.feature.name in valid_feature_names
+            ]
+        )

flag_engine/identities/traits/constants.py

@@ -0,0 +1 @@
+TRAIT_STRING_VALUE_MAX_LENGTH: int = 2000

flag_engine/identities/traits/models.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel, Field
+
+from flag_engine.identities.traits.types import ContextValue
+
+
+class TraitModel(BaseModel):
+    trait_key: str
+    trait_value: ContextValue = Field(...)

flag_engine/identities/traits/types.py

@@ -0,0 +1,62 @@
+import re
+from decimal import Decimal
+from typing import Any, Union, get_args
+
+from pydantic import BeforeValidator
+from pydantic.types import AllowInfNan, StrictBool, StringConstraints
+from typing_extensions import Annotated, TypeGuard
+
+from flag_engine.identities.traits.constants import TRAIT_STRING_VALUE_MAX_LENGTH
+
+_UnconstrainedContextValue = Union[None, int, float, bool, str]
+
+
+def map_any_value_to_trait_value(value: Any) -> _UnconstrainedContextValue:
+    """
+    Try to coerce a value of arbitrary type to a trait value type.
+    Union member-specific constraints, such as max string value length, are ignored here.
+    Replicate behaviour from marshmallow/pydantic V1 for number-like strings.
+    For decimals return an int in case of unset exponent.
+    When in doubt, return string.
+
+    Supposed to be used as a `pydantic.BeforeValidator`.
+    """
+    if _is_trait_value(value):
+        if isinstance(value, str):
+            return _map_string_value_to_trait_value(value)
+        return value
+    if isinstance(value, Decimal):
+        if value.as_tuple().exponent:
+            return float(str(value))
+        return int(value)
+    return str(value)
+
+
+_int_pattern = re.compile(r"-?[0-9]+")
+_float_pattern = re.compile(r"-?[0-9]+\.[0-9]+")
+
+
+def _map_string_value_to_trait_value(value: str) -> _UnconstrainedContextValue:
+    if _int_pattern.fullmatch(value):
+        return int(value)
+    if _float_pattern.fullmatch(value):
+        return float(value)
+    return value
+
+
+def _is_trait_value(value: Any) -> TypeGuard[_UnconstrainedContextValue]:
+    return isinstance(value, get_args(_UnconstrainedContextValue))
+
+
+ContextValue = Annotated[
+    Union[
+        None,
+        StrictBool,
+        Annotated[float, AllowInfNan(False)],
+        int,
+        Annotated[str, StringConstraints(max_length=TRAIT_STRING_VALUE_MAX_LENGTH)],
+    ],
+    BeforeValidator(map_any_value_to_trait_value),
+]
+
+TraitValue = ContextValue

flag_engine/organisations/models.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+
+
+class OrganisationModel(BaseModel):
+    id: int
+    name: str
+    feature_analytics: bool = False
+    stop_serving_flags: bool = False
+    persist_trait_data: bool = True
+
+    @property
+    def unique_slug(self) -> str:
+        return str(self.id) + "-" + self.name