flagsmith 5.2.0__tar.gz → 5.3.0__tar.gz

{flagsmith-5.2.0 → flagsmith-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith
-Version: 5.2.0
+Version: 5.3.0
 Summary: Flagsmith Python SDK
 License: BSD3
 License-File: LICENSE
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: flagsmith-flag-engine (>=10.0.3,<11.0.0)
+Requires-Dist: flagsmith-flag-engine (>=10.0.4,<11.0.0)
 Requires-Dist: iso8601 (>=2.1.0,<3.0.0) ; python_version < "3.11"
 Requires-Dist: requests (>=2.32.3,<3.0.0)
 Requires-Dist: requests-futures (>=1.0.1,<2.0.0)

{flagsmith-5.2.0 → flagsmith-5.3.0}/flagsmith/flagsmith.py

@@ -21,7 +21,13 @@ from flagsmith.mappers import (
     map_segment_results_to_identity_segments,
     resolve_trait_values,
 )
-from flagsmith.models import DefaultFlag, Flags, Segment
+from flagsmith.models import (
+    DefaultFlag,
+    Flags,
+    Segment,
+    SegmentOverridesIndex,
+    build_segment_overrides_index,
+)
 from flagsmith.offline_handlers import OfflineHandler
 from flagsmith.polling_manager import EnvironmentDataPollingManager
 from flagsmith.streaming_manager import EventStreamManager
@@ -117,7 +123,8 @@ class Flagsmith:
         self._pipeline_analytics_processor: typing.Optional[
             PipelineAnalyticsProcessor
         ] = None
-        self._evaluation_context: typing.Optional[SDKEvaluationContext] = None
+        self.__evaluation_context: typing.Optional[SDKEvaluationContext] = None
+        self._segment_overrides_index: SegmentOverridesIndex = {}
         self._environment_updated_at: typing.Optional[datetime] = None
 
         # argument validation
@@ -356,6 +363,26 @@ class Flagsmith:
             except (KeyError, TypeError, ValueError):
                 logger.exception("Error parsing environment document")
 
+    @property
+    def _evaluation_context(self) -> typing.Optional[SDKEvaluationContext]:
+        return self.__evaluation_context
+
+    @_evaluation_context.setter
+    def _evaluation_context(
+        self, context: typing.Optional[SDKEvaluationContext]
+    ) -> None:
+        """Swap in a new evaluation context and rebuild the overrides index.
+
+        The index maps feature_name -> segments that override it. Built once
+        per refresh and reused across every subsequent per-identity lazy
+        resolution; rebuilding here keeps it in sync with the current doc
+        without any hot-path cost.
+        """
+        self.__evaluation_context = context
+        self._segment_overrides_index = (
+            build_segment_overrides_index(context) if context is not None else {}
+        )
+
     def _get_headers(
         self,
         environment_key: str,
@@ -407,12 +434,12 @@ class Flagsmith:
             identifier=identifier,
             traits=traits,
         )
-        evaluation_result = engine.get_evaluation_result(
+        # Lazy: defer per-feature evaluation until the caller actually reads
+        # a flag. Hot for callers that only read one or a few flags out of a
+        # large environment.
+        return Flags.from_evaluation_context(
             context=context,
-        )
-
-        return Flags.from_evaluation_result(
-            evaluation_result=evaluation_result,
+            overrides_index=self._segment_overrides_index,
             analytics_processor=self._analytics_processor,
             default_flag_handler=self.default_flag_handler,
             pipeline_analytics_processor=self._pipeline_analytics_processor,

{flagsmith-5.2.0 → flagsmith-5.3.0}/flagsmith/models.py

@@ -3,9 +3,37 @@ from __future__ import annotations
 import typing
 from dataclasses import dataclass, field
 
+from flag_engine import engine
+from flag_engine.context.types import SegmentContext
+
 from flagsmith.analytics import AnalyticsProcessor, PipelineAnalyticsProcessor
 from flagsmith.exceptions import FlagsmithFeatureDoesNotExistError
-from flagsmith.types import SDKEvaluationResult, SDKFlagResult
+from flagsmith.types import (
+    FeatureMetadata,
+    SDKEvaluationContext,
+    SDKEvaluationResult,
+    SDKFlagResult,
+    SegmentMetadata,
+)
+
+SegmentOverridesIndex = typing.Dict[
+    str, typing.List[SegmentContext[SegmentMetadata, FeatureMetadata]]
+]
+
+
+def build_segment_overrides_index(
+    context: SDKEvaluationContext,
+) -> SegmentOverridesIndex:
+    """Map feature_name -> segments that carry an override for that feature.
+
+    Computed once per environment-document refresh so the lazy eval path
+    can walk only the segments actually relevant to a given flag.
+    """
+    index: SegmentOverridesIndex = {}
+    for segment_context in (context.get("segments") or {}).values():
+        for override in segment_context.get("overrides") or ():
+            index.setdefault(override["name"], []).append(segment_context)
+    return index
 
 
 @dataclass
@@ -60,6 +88,14 @@ class Flags:
     _pipeline_analytics_processor: typing.Optional[PipelineAnalyticsProcessor] = None
     _identity_identifier: typing.Optional[str] = None
     _traits: typing.Optional[typing.Dict[str, typing.Any]] = None
+    # Lazy-evaluation state. When `_context` is set, `flags` is a
+    # per-feature memo rather than a fully-materialised snapshot; unseen
+    # features are resolved on demand via the engine primitives and
+    # cached back into `flags`. Left as `None` by the eager code
+    # paths (`from_evaluation_result` / `from_api_flags`).
+    _context: typing.Optional[SDKEvaluationContext] = None
+    _overrides_index: typing.Optional[SegmentOverridesIndex] = None
+    _fully_materialised: bool = False
 
     @classmethod
     def from_evaluation_result(
@@ -86,6 +122,37 @@ class Flags:
             _traits=traits,
         )
 
+    @classmethod
+    def from_evaluation_context(
+        cls,
+        context: SDKEvaluationContext,
+        overrides_index: SegmentOverridesIndex,
+        analytics_processor: typing.Optional[AnalyticsProcessor],
+        default_flag_handler: typing.Optional[typing.Callable[[str], DefaultFlag]],
+        pipeline_analytics_processor: typing.Optional[
+            PipelineAnalyticsProcessor
+        ] = None,
+        identity_identifier: typing.Optional[str] = None,
+        traits: typing.Optional[typing.Dict[str, typing.Any]] = None,
+    ) -> Flags:
+        """Build a lazy `Flags` backed by an evaluation context.
+
+        No engine work is done here — flags are resolved on first access
+        via :meth:`_resolve_flag`. Reusing the same `overrides_index`
+        across calls amortises its construction cost (it's rebuilt only
+        when the environment doc refreshes, not per identity).
+        """
+        return cls(
+            flags={},
+            default_flag_handler=default_flag_handler,
+            _analytics_processor=analytics_processor,
+            _pipeline_analytics_processor=pipeline_analytics_processor,
+            _identity_identifier=identity_identifier,
+            _traits=traits,
+            _context=context,
+            _overrides_index=overrides_index,
+        )
+
     @classmethod
     def from_api_flags(
         cls,
@@ -116,8 +183,21 @@ class Flags:
         """
         Get a list of all Flag objects.
 
+        In lazy mode, the caller has signalled they want every flag, so
+        we run the bulk evaluator once on the full context and copy the
+        results into the per-flag cache. Cheaper than asking the engine
+        for each feature one at a time.
+
         :return: list of Flag objects.
         """
+        if self._context is not None and not self._fully_materialised:
+            result = engine.get_evaluation_result(self._context)
+            for feature_name, flag_result in result["flags"].items():
+                if feature_name not in self.flags:
+                    self.flags[feature_name] = Flag.from_evaluation_result(
+                        flag_result,
+                    )
+            self._fully_materialised = True
         return list(self.flags.values())
 
     def is_feature_enabled(self, feature_name: str) -> bool:
@@ -151,11 +231,23 @@ class Flags:
         try:
             flag = self.flags[feature_name]
         except KeyError:
-            if self.default_flag_handler:
+            # Lazy path: if this `Flags` wraps an evaluation context and
+            # the feature exists in it, resolve and memoise now. Otherwise
+            # fall through to the default_flag_handler / not-found error,
+            # preserving the eager-mode behaviour byte-for-byte.
+            if (
+                self._context is not None
+                and self._overrides_index is not None
+                and feature_name in (self._context.get("features") or {})
+            ):
+                flag = self._resolve_flag(feature_name)
+                self.flags[feature_name] = flag
+            elif self.default_flag_handler:
                 return self.default_flag_handler(feature_name)
-            raise FlagsmithFeatureDoesNotExistError(
-                "Feature does not exist: %s" % feature_name
-            )
+            else:
+                raise FlagsmithFeatureDoesNotExistError(
+                    "Feature does not exist: %s" % feature_name
+                )
 
         if self._analytics_processor and hasattr(flag, "feature_name"):
             self._analytics_processor.track_feature(flag.feature_name)
@@ -171,6 +263,35 @@ class Flags:
 
         return flag
 
+    def _resolve_flag(self, feature_name: str) -> Flag:
+        """Evaluate a single feature against the lazy context.
+
+        Goes through the engine's public `get_evaluation_result` so
+        identity-key enrichment, multivariate hashing, percentage-split
+        rules and override-priority handling all stay where they
+        belong (in the engine). The performance win comes from passing
+        a *trimmed* context — just the queried feature plus the segments
+        that could override it, looked up in O(1) via the precomputed
+        reverse index — so the engine's full pipeline runs against an
+        input small enough to evaluate in ~1 µs.
+        """
+        context = self._context
+        overrides_index = self._overrides_index
+        # `get_flag` / `all_flags` gate this call behind the same
+        # non-None checks; assert here so type checkers can narrow.
+        assert context is not None and overrides_index is not None
+
+        trimmed: SDKEvaluationContext = {
+            **context,
+            "features": {feature_name: context["features"][feature_name]},
+            "segments": {
+                segment_context["key"]: segment_context
+                for segment_context in overrides_index.get(feature_name, ())
+            },
+        }
+        result = engine.get_evaluation_result(trimmed)
+        return Flag.from_evaluation_result(result["flags"][feature_name])
+
 
 @dataclass
 class Segment:

{flagsmith-5.2.0 → flagsmith-5.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "flagsmith"
-version = "5.2.0"
+version = "5.3.0"
 description = "Flagsmith Python SDK"
 authors = ["Flagsmith <support@flagsmith.com>"]
 license = "BSD3"
@@ -10,7 +10,7 @@ documentation = "https://docs.flagsmith.com"
 packages = [{ include = "flagsmith" }]
 
 [tool.poetry.dependencies]
-flagsmith-flag-engine = "^10.0.3"
+flagsmith-flag-engine = "^10.0.4"
 iso8601 = { version = "^2.1.0", python = "<3.11" }
 python = ">=3.9,<4"
 requests = "^2.32.3"