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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith-flag-engine
-Version: 6.0.2
+Version: 7.0.0
 Summary: Flag engine for the Flagsmith API.
 Home-page: https://github.com/Flagsmith/flagsmith-engine
 Author: Flagsmith
@@ -8,14 +8,16 @@ 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
+Classifier: Programming Language :: Python :: 3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
-Requires-Dist: pydantic<3,>=2.3.0
-Requires-Dist: pydantic-collections<1,>=0.5.1
-Requires-Dist: semver>=3.0.1
+Requires-Dist: jsonpath-rfc9535<1,>=0.1.5
+Requires-Dist: semver<4,>=3.0.4
+Requires-Dist: typing-extensions<5,>=4.14.1
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

flagsmith_flag_engine-7.0.0/flag_engine/context/mappers.py

@@ -0,0 +1,38 @@
+import re
+import typing
+from decimal import Decimal
+
+from flag_engine.segments.types import ContextValue, is_context_value
+
+
+def map_any_value_to_context_value(value: typing.Any) -> ContextValue:
+    """
+    Try to coerce a value of arbitrary type to a context 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.
+
+    Can be used as a `pydantic.BeforeValidator`.
+    """
+    if is_context_value(value):
+        if isinstance(value, str):
+            return _map_string_value_to_context_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_context_value(value: str) -> ContextValue:
+    if _int_pattern.fullmatch(value):
+        return int(value)
+    if _float_pattern.fullmatch(value):
+        return float(value)
+    return value

flagsmith_flag_engine-7.0.0/flag_engine/context/types.py

@@ -0,0 +1,72 @@
+# generated by datamodel-codegen:
+#   filename:  https://raw.githubusercontent.com/Flagsmith/flagsmith/main/sdk/evaluation-context.json  # noqa: E501
+#   timestamp: 2025-08-25T11:10:31+00:00
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+from typing_extensions import NotRequired
+
+from flag_engine.segments.types import ConditionOperator, ContextValue, 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, ContextValue]]
+
+
+class StrValueSegmentCondition(TypedDict):
+    property: str
+    operator: ConditionOperator
+    value: str
+
+
+class InOperatorSegmentCondition(TypedDict):
+    property: str
+    operator: Literal["IN"]
+    value: List[str]
+
+
+SegmentCondition = Union[StrValueSegmentCondition, InOperatorSegmentCondition]
+
+
+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-7.0.0/flag_engine/engine.py

@@ -0,0 +1,11 @@
+from flag_engine.context.types import EvaluationContext
+from flag_engine.result.types import EvaluationResult
+from flag_engine.segments.evaluator import get_evaluation_result
+from flag_engine.segments.types import ContextValue
+
+__all__ = (
+    "ContextValue",
+    "EvaluationContext",
+    "EvaluationResult",
+    "get_evaluation_result",
+)

flagsmith_flag_engine-7.0.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-7.0.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")

flagsmith_flag_engine-7.0.0/flag_engine/segments/evaluator.py

@@ -0,0 +1,374 @@
+import json
+import operator
+import re
+import typing
+import warnings
+from contextlib import suppress
+from functools import lru_cache, wraps
+
+import jsonpath_rfc9535
+import semver
+
+from flag_engine.context.mappers import map_any_value_to_context_value
+from flag_engine.context.types import (
+    EvaluationContext,
+    FeatureContext,
+    SegmentCondition,
+    SegmentContext,
+    SegmentRule,
+    StrValueSegmentCondition,
+)
+from flag_engine.result.types import EvaluationResult, FlagResult, SegmentResult
+from flag_engine.segments import constants
+from flag_engine.segments.types import ConditionOperator, ContextValue, is_context_value
+from flag_engine.segments.utils import escape_double_quotes, get_matching_function
+from flag_engine.utils.hashing import get_hashed_percentage_for_object_ids
+from flag_engine.utils.semver import is_semver
+from flag_engine.utils.types import SupportsStr, get_casting_function
+
+
+def get_evaluation_result(context: EvaluationContext) -> EvaluationResult:
+    """
+    Get the evaluation result for a given context.
+
+    :param context: the evaluation context
+    :return: EvaluationResult containing the context, flags, and segments
+    """
+    segments: list[SegmentResult] = []
+    segment_feature_contexts: dict[SupportsStr, FeatureContext] = {}
+    for segment_context in (context.get("segments") or {}).values():
+        if not is_context_in_segment(context, segment_context):
+            continue
+
+        segments.append(
+            {
+                "key": segment_context["key"],
+                "name": segment_context["name"],
+            }
+        )
+
+        if overrides := segment_context.get("overrides"):
+            for override_feature_context in overrides:
+                feature_key = override_feature_context["feature_key"]
+                if (
+                    feature_key not in segment_feature_contexts
+                    or override_feature_context.get(
+                        "priority",
+                        constants.DEFAULT_PRIORITY,
+                    )
+                    < segment_feature_contexts[feature_key].get(
+                        "priority",
+                        constants.DEFAULT_PRIORITY,
+                    )
+                ):
+                    segment_feature_contexts[feature_key] = override_feature_context
+
+    identity_key = get_context_value(context, "$.identity.key")
+    flags: list[FlagResult] = [
+        (
+            {
+                "enabled": segment_feature_context["enabled"],
+                "feature_key": segment_feature_context["feature_key"],
+                "name": segment_feature_context["name"],
+                "reason": f"TARGETING_MATCH; segment={segment_context['name']}",
+                "value": segment_feature_context.get("value"),
+            }
+            if (
+                segment_feature_context := segment_feature_contexts.get(
+                    feature_context["feature_key"],
+                )
+            )
+            else get_flag_result_from_feature_context(
+                feature_context=feature_context,
+                key=identity_key,
+            )
+        )
+        for feature_context in (context.get("features") or {}).values()
+    ]
+
+    return {
+        "context": context,
+        "flags": flags,
+        "segments": segments,
+    }
+
+
+def get_flag_result_from_feature_context(
+    feature_context: FeatureContext,
+    key: typing.Optional[SupportsStr],
+) -> FlagResult:
+    """
+    Get a feature value from the feature context
+    for a given key.
+
+    :param feature_context: the feature context
+    :param key: the key to get the value for
+    :return: the value for the key in the feature context
+    """
+    if key is not None and (variants := feature_context.get("variants")):
+        percentage_value = get_hashed_percentage_for_object_ids(
+            [feature_context["key"], key]
+        )
+
+        # We expect `variants` to be pre-sorted in order of persistence. 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
+
+        for variant in variants:
+            limit = (weight := variant["weight"]) + start_percentage
+            if start_percentage <= percentage_value < limit:
+                return {
+                    "enabled": feature_context["enabled"],
+                    "feature_key": feature_context["feature_key"],
+                    "name": feature_context["name"],
+                    "reason": f"SPLIT; weight={weight}",
+                    "value": variant["value"],
+                }
+
+            start_percentage = limit
+
+    return {
+        "enabled": feature_context["enabled"],
+        "feature_key": feature_context["feature_key"],
+        "name": feature_context["name"],
+        "reason": "DEFAULT",
+        "value": feature_context["value"],
+    }
+
+
+def is_context_in_segment(
+    context: EvaluationContext,
+    segment_context: SegmentContext,
+) -> bool:
+    return bool(rules := segment_context["rules"]) and all(
+        context_matches_rule(
+            context=context, rule=rule, segment_key=segment_context["key"]
+        )
+        for rule in rules
+    )
+
+
+def context_matches_rule(
+    context: EvaluationContext,
+    rule: SegmentRule,
+    segment_key: SupportsStr,
+) -> bool:
+    matches_conditions = (
+        get_matching_function(rule["type"])(
+            [
+                context_matches_condition(
+                    context=context,
+                    condition=condition,
+                    segment_key=segment_key,
+                )
+                for condition in conditions
+            ]
+        )
+        if (conditions := rule.get("conditions"))
+        else True
+    )
+
+    return matches_conditions and all(
+        context_matches_rule(
+            context=context,
+            rule=rule,
+            segment_key=segment_key,
+        )
+        for rule in rule.get("rules") or []
+    )
+
+
+def context_matches_condition(
+    context: EvaluationContext,
+    condition: SegmentCondition,
+    segment_key: SupportsStr,
+) -> bool:
+    context_value = (
+        get_context_value(context, condition_property)
+        if (condition_property := condition.get("property"))
+        else None
+    )
+
+    if condition["operator"] == constants.IN:
+        if isinstance(segment_value := condition["value"], list):
+            in_values = segment_value
+        else:
+            try:
+                in_values = json.loads(segment_value)
+                # Only accept JSON lists.
+                # Ideally, we should use something like pydantic.TypeAdapter[list[str]],
+                # but we aim to ditch the pydantic dependency in the future.
+                if not isinstance(in_values, list):
+                    raise ValueError
+            except ValueError:
+                in_values = segment_value.split(",")
+        in_values = [str(value) for value in in_values]
+        # Guard against comparing boolean values to numeric strings.
+        if isinstance(context_value, int) and not (
+            context_value is True or context_value is False
+        ):
+            context_value = str(context_value)
+        return context_value in in_values
+
+    condition = typing.cast(StrValueSegmentCondition, condition)
+
+    if condition["operator"] == constants.PERCENTAGE_SPLIT:
+        if context_value is not None:
+            object_ids = [segment_key, context_value]
+        else:
+            object_ids = [segment_key, get_context_value(context, "$.identity.key")]
+
+        float_value = float(condition["value"])
+        return get_hashed_percentage_for_object_ids(object_ids) <= float_value
+
+    if condition["operator"] == constants.IS_NOT_SET:
+        return context_value is None
+
+    if condition["operator"] == constants.IS_SET:
+        return context_value is not None
+
+    return (
+        _matches_context_value(condition, context_value)
+        if context_value is not None
+        else False
+    )
+
+
+def get_context_value(
+    context: EvaluationContext,
+    property: str,
+) -> ContextValue:
+    value = None
+    if property.startswith("$."):
+        value = _get_context_value_getter(property)(context)
+    elif identity_context := context.get("identity"):
+        if traits := identity_context.get("traits"):
+            value = traits.get(property)
+    return map_any_value_to_context_value(value)
+
+
+def _matches_context_value(
+    condition: StrValueSegmentCondition,
+    context_value: ContextValue,
+) -> bool:
+    if matcher := MATCHERS_BY_OPERATOR.get(condition["operator"]):
+        return matcher(condition["value"], context_value)
+
+    return False
+
+
+def _evaluate_not_contains(
+    segment_value: typing.Optional[str],
+    context_value: ContextValue,
+) -> bool:
+    return isinstance(context_value, str) and str(segment_value) not in context_value
+
+
+def _evaluate_regex(
+    segment_value: typing.Optional[str],
+    context_value: ContextValue,
+) -> bool:
+    return (
+        context_value is not None
+        and re.compile(str(segment_value)).match(str(context_value)) is not None
+    )
+
+
+def _evaluate_modulo(
+    segment_value: typing.Optional[str],
+    context_value: ContextValue,
+) -> bool:
+    if not isinstance(context_value, (int, float)):
+        return False
+
+    if not segment_value:
+        return False
+
+    try:
+        divisor_part, remainder_part = segment_value.split("|")
+        divisor = float(divisor_part)
+        remainder = float(remainder_part)
+    except ValueError:
+        return False
+
+    return context_value % divisor == remainder
+
+
+def _context_value_typed(
+    func: typing.Callable[..., bool],
+) -> typing.Callable[[typing.Optional[str], ContextValue], bool]:
+    @wraps(func)
+    def inner(
+        segment_value: typing.Optional[str],
+        context_value: typing.Union[ContextValue, semver.Version],
+    ) -> bool:
+        with suppress(TypeError, ValueError):
+            if isinstance(context_value, str) and is_semver(segment_value):
+                context_value = semver.Version.parse(
+                    context_value,
+                )
+            match_value = get_casting_function(context_value)(segment_value)
+            return func(context_value, match_value)
+        return False
+
+    return inner
+
+
+MATCHERS_BY_OPERATOR: dict[
+    ConditionOperator, typing.Callable[[typing.Optional[str], ContextValue], bool]
+] = {
+    constants.NOT_CONTAINS: _evaluate_not_contains,
+    constants.REGEX: _evaluate_regex,
+    constants.MODULO: _evaluate_modulo,
+    constants.EQUAL: _context_value_typed(operator.eq),
+    constants.GREATER_THAN: _context_value_typed(operator.gt),
+    constants.GREATER_THAN_INCLUSIVE: _context_value_typed(operator.ge),
+    constants.LESS_THAN: _context_value_typed(operator.lt),
+    constants.LESS_THAN_INCLUSIVE: _context_value_typed(operator.le),
+    constants.NOT_EQUAL: _context_value_typed(operator.ne),
+    constants.CONTAINS: _context_value_typed(operator.contains),
+}
+
+
+@lru_cache
+def _get_context_value_getter(
+    property: str,
+) -> typing.Callable[[EvaluationContext], ContextValue]:
+    """
+    Get a function to retrieve a context value based on property value,
+    assumed to be either a JSONPath string or a trait key.
+
+    :param property: The property to retrieve the value for.
+    :return: A function that takes an EvaluationContext and returns the value.
+    """
+    try:
+        compiled_query = jsonpath_rfc9535.compile(property)
+    except jsonpath_rfc9535.JSONPathSyntaxError:
+        # This covers a rare case when a trait starting with "$.",
+        # but not a valid JSONPath, is used.
+        compiled_query = jsonpath_rfc9535.compile(
+            f'$.identity.traits["{escape_double_quotes(property)}"]',
+        )
+
+    def getter(context: EvaluationContext) -> ContextValue:
+        if typing.TYPE_CHECKING:  # pragma: no cover
+            # Ugly hack to satisfy mypy :(
+            data = dict(context)
+        else:
+            data = context
+        try:
+            if result := compiled_query.find_one(data):
+                if is_context_value(value := result.value):
+                    return value
+            return None
+        except jsonpath_rfc9535.JSONPathError:  # pragma: no cover
+            # This is supposed to be unreachable, but if it happens,
+            # we log a warning and return None.
+            warnings.warn(
+                f"Failed to evaluate JSONPath query '{property}' in context: {context}",
+                RuntimeWarning,
+            )
+            return None
+
+    return getter

flagsmith_flag_engine-7.0.0/flag_engine/segments/types.py

@@ -0,0 +1,38 @@
+from typing import Any, Literal, Union, get_args
+
+from typing_extensions import TypeGuard
+
+ConditionOperator = Literal[
+    "EQUAL",
+    "GREATER_THAN",
+    "LESS_THAN",
+    "LESS_THAN_INCLUSIVE",
+    "CONTAINS",
+    "GREATER_THAN_INCLUSIVE",
+    "NOT_CONTAINS",
+    "NOT_EQUAL",
+    "REGEX",
+    "PERCENTAGE_SPLIT",
+    "MODULO",
+    "IS_SET",
+    "IS_NOT_SET",
+    "IN",
+]
+
+RuleType = Literal[
+    "ALL",
+    "ANY",
+    "NONE",
+]
+
+
+ContextValue = Union[None, int, float, bool, str]
+_context_value_types = get_args(ContextValue)
+
+
+def is_context_value(value: Any) -> TypeGuard[ContextValue]:
+    """
+    Check if the value is a valid context value type.
+    This function is used to determine if a value can be treated as a context value.
+    """
+    return isinstance(value, _context_value_types)

flagsmith_flag_engine-7.0.0/flag_engine/segments/utils.py

@@ -0,0 +1,24 @@
+import typing
+
+from flag_engine.segments.types import RuleType
+
+
+def get_matching_function(
+    segment_type: RuleType,
+) -> typing.Callable[[typing.Iterable[object]], bool]:
+    return {
+        "ANY": any,
+        "ALL": all,
+        "NONE": none,
+    }[segment_type]
+
+
+def none(iterable: typing.Iterable[object]) -> bool:
+    return not any(iterable)
+
+
+def escape_double_quotes(value: str) -> str:
+    """
+    Escape double quotes in a string for JSONPath compatibility.
+    """
+    return value.replace('"', '\\"')

{flagsmith_flag_engine-6.0.2 → flagsmith_flag_engine-7.0.0}/flag_engine/utils/types.py

@@ -3,7 +3,7 @@ from functools import singledispatch
 
 import semver
 
-from flag_engine.identities.traits.types import ContextValue
+from flag_engine.segments.types import ContextValue
 from flag_engine.utils.semver import remove_semver_suffix
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith-flag-engine
-Version: 6.0.2
+Version: 7.0.0
 Summary: Flag engine for the Flagsmith API.
 Home-page: https://github.com/Flagsmith/flagsmith-engine
 Author: Flagsmith
@@ -8,14 +8,16 @@ 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
+Classifier: Programming Language :: Python :: 3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
-Requires-Dist: pydantic<3,>=2.3.0
-Requires-Dist: pydantic-collections<1,>=0.5.1
-Requires-Dist: semver>=3.0.1
+Requires-Dist: jsonpath-rfc9535<1,>=0.1.5
+Requires-Dist: semver<4,>=3.0.4
+Requires-Dist: typing-extensions<5,>=4.14.1
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier