flagsmith 5.1.1__tar.gz → 5.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith
-Version: 5.1.1
+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.3.0/flagsmith/__init__.py

@@ -0,0 +1,6 @@
+from flagsmith import webhooks
+from flagsmith.analytics import PipelineAnalyticsConfig
+from flagsmith.flagsmith import Flagsmith
+from flagsmith.version import __version__
+
+__all__ = ("Flagsmith", "PipelineAnalyticsConfig", "webhooks", "__version__")

flagsmith-5.3.0/flagsmith/analytics.py

@@ -0,0 +1,229 @@
+import atexit
+import json
+import logging
+import threading
+import time
+import typing
+from dataclasses import dataclass
+from datetime import datetime
+
+from requests_futures.sessions import FuturesSession  # type: ignore
+
+from flagsmith.version import __version__
+
+logger = logging.getLogger(__name__)
+
+ANALYTICS_ENDPOINT: typing.Final[str] = "analytics/flags/"
+
+# Used to control how often we send data(in seconds)
+ANALYTICS_TIMER: typing.Final[int] = 10
+
+session = FuturesSession(max_workers=4)
+
+
+class AnalyticsProcessor:
+    """
+    AnalyticsProcessor is used to track how often individual Flags are evaluated within
+    the Flagsmith SDK. Docs: https://docs.flagsmith.com/advanced-use/flag-analytics.
+    """
+
+    def __init__(
+        self, environment_key: str, base_api_url: str, timeout: typing.Optional[int] = 3
+    ):
+        """
+        Initialise the AnalyticsProcessor to handle sending analytics on flag usage to
+        the Flagsmith API.
+
+        :param environment_key: environment key obtained from the Flagsmith UI
+        :param base_api_url: base api url to override when using self hosted version
+        :param timeout: used to tell requests to stop waiting for a response after a
+            given number of seconds
+        """
+        self.analytics_endpoint = base_api_url + ANALYTICS_ENDPOINT
+        self.environment_key = environment_key
+        self._last_flushed = datetime.now()
+        self.analytics_data: typing.MutableMapping[str, typing.Any] = {}
+        self.timeout = timeout or 3
+
+    def flush(self) -> None:
+        """
+        Sends all the collected data to the api asynchronously and resets the timer
+        """
+
+        if not self.analytics_data:
+            return
+        session.post(
+            self.analytics_endpoint,
+            data=json.dumps(self.analytics_data),
+            timeout=self.timeout,
+            headers={
+                "X-Environment-Key": self.environment_key,
+                "Content-Type": "application/json",
+            },
+        )
+
+        self.analytics_data.clear()
+        self._last_flushed = datetime.now()
+
+    def track_feature(self, feature_name: str) -> None:
+        self.analytics_data[feature_name] = self.analytics_data.get(feature_name, 0) + 1
+        if (datetime.now() - self._last_flushed).seconds > ANALYTICS_TIMER:
+            self.flush()
+
+
+@dataclass
+class PipelineAnalyticsConfig:
+    analytics_server_url: str
+    max_buffer_items: int = 1000
+    flush_interval_seconds: float = 10.0
+
+
+class PipelineAnalyticsProcessor:
+    """
+    Buffered analytics processor that sends per-evaluation and custom events
+    to the Flagsmith pipeline analytics endpoint in batches.
+
+    Evaluation events are deduplicated within each flush window. Events are
+    flushed periodically via a background timer or when the buffer is full.
+    """
+
+    def __init__(
+        self,
+        config: PipelineAnalyticsConfig,
+        environment_key: str,
+    ) -> None:
+        url = config.analytics_server_url
+        if not url.endswith("/"):
+            url = f"{url}/"
+        self._batch_endpoint = f"{url}v1/analytics/batch"
+        self._environment_key = environment_key
+        self._max_buffer = config.max_buffer_items
+        self._flush_interval_seconds = config.flush_interval_seconds
+
+        self._buffer: typing.List[typing.Dict[str, typing.Any]] = []
+        self._dedup_keys: typing.Dict[str, str] = {}
+        self._lock = threading.Lock()
+        self._timer: typing.Optional[threading.Timer] = None
+
+    def record_evaluation_event(
+        self,
+        flag_key: str,
+        enabled: bool,
+        value: typing.Any,
+        identity_identifier: typing.Optional[str] = None,
+        traits: typing.Optional[typing.Dict[str, typing.Any]] = None,
+    ) -> None:
+        fingerprint = f"{identity_identifier or 'none'}|{enabled}|{value}"
+        should_flush = False
+
+        with self._lock:
+            if self._dedup_keys.get(flag_key) == fingerprint:
+                return
+            self._dedup_keys[flag_key] = fingerprint
+            self._buffer.append(
+                {
+                    "event_id": flag_key,
+                    "event_type": "flag_evaluation",
+                    "evaluated_at": int(time.time() * 1000),
+                    "identity_identifier": identity_identifier,
+                    "enabled": enabled,
+                    "value": value,
+                    "traits": dict(traits) if traits else None,
+                    "metadata": {"sdk_version": __version__},
+                }
+            )
+            if len(self._buffer) >= self._max_buffer:
+                should_flush = True
+
+        if should_flush:
+            self.flush()
+
+    def record_custom_event(
+        self,
+        event_name: str,
+        identity_identifier: typing.Optional[str] = None,
+        traits: typing.Optional[typing.Dict[str, typing.Any]] = None,
+        metadata: typing.Optional[typing.Dict[str, typing.Any]] = None,
+    ) -> None:
+        should_flush = False
+
+        with self._lock:
+            self._buffer.append(
+                {
+                    "event_id": event_name,
+                    "event_type": "custom_event",
+                    "evaluated_at": int(time.time() * 1000),
+                    "identity_identifier": identity_identifier,
+                    "enabled": None,
+                    "value": None,
+                    "traits": dict(traits) if traits else None,
+                    "metadata": {**(metadata or {}), "sdk_version": __version__},
+                }
+            )
+            if len(self._buffer) >= self._max_buffer:
+                should_flush = True
+
+        if should_flush:
+            self.flush()
+
+    def flush(self) -> None:
+        with self._lock:
+            if not self._buffer:
+                return
+            events = self._buffer
+            self._buffer = []
+            self._dedup_keys.clear()
+
+        payload = json.dumps(
+            {"events": events, "environment_key": self._environment_key}
+        )
+        try:
+            future = session.post(
+                self._batch_endpoint,
+                data=payload,
+                timeout=3,
+                headers={
+                    "Content-Type": "application/json; charset=utf-8",
+                    "X-Environment-Key": self._environment_key,
+                    "Flagsmith-SDK-User-Agent": f"flagsmith-python-client/{__version__}",
+                },
+            )
+        except RuntimeError:
+            logger.debug("Skipping flush: thread pool already shut down")
+            return
+        future.add_done_callback(lambda f: self._handle_flush_result(f, events))
+
+    def _handle_flush_result(
+        self,
+        future: typing.Any,
+        events: typing.List[typing.Dict[str, typing.Any]],
+    ) -> None:
+        try:
+            response = future.result()
+            response.raise_for_status()
+        except Exception:
+            logger.warning(
+                "Failed to flush pipeline analytics, re-queuing events", exc_info=True
+            )
+            with self._lock:
+                self._buffer = events + self._buffer
+                self._buffer = self._buffer[: self._max_buffer]
+
+    def start(self) -> None:
+        self._schedule_flush()
+        atexit.register(self.stop)
+
+    def stop(self) -> None:
+        atexit.unregister(self.stop)
+        if self._timer is not None:
+            self._timer.cancel()
+        self.flush()
+
+    def _schedule_flush(self) -> None:
+        self._timer = threading.Timer(self._flush_interval_seconds, self._timer_flush)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _timer_flush(self) -> None:
+        self.flush()
+        self._schedule_flush()

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

@@ -8,15 +8,26 @@ from flag_engine import engine
 from requests.adapters import HTTPAdapter
 from urllib3 import Retry
 
-from flagsmith.analytics import AnalyticsProcessor
+from flagsmith.analytics import (
+    AnalyticsProcessor,
+    PipelineAnalyticsConfig,
+    PipelineAnalyticsProcessor,
+)
 from flagsmith.exceptions import FlagsmithAPIError, FlagsmithClientError
 from flagsmith.mappers import (
     map_context_and_identity_data_to_context,
     map_environment_document_to_context,
     map_environment_document_to_environment_updated_at,
     map_segment_results_to_identity_segments,
+    resolve_trait_values,
+)
+from flagsmith.models import (
+    DefaultFlag,
+    Flags,
+    Segment,
+    SegmentOverridesIndex,
+    build_segment_overrides_index,
 )
-from flagsmith.models import DefaultFlag, Flags, Segment
 from flagsmith.offline_handlers import OfflineHandler
 from flagsmith.polling_manager import EnvironmentDataPollingManager
 from flagsmith.streaming_manager import EventStreamManager
@@ -63,6 +74,7 @@ class Flagsmith:
         environment_refresh_interval_seconds: typing.Union[int, float] = 60,
         retries: typing.Optional[Retry] = None,
         enable_analytics: bool = False,
+        pipeline_analytics_config: typing.Optional[PipelineAnalyticsConfig] = None,
         default_flag_handler: typing.Optional[
             typing.Callable[[str], DefaultFlag]
         ] = None,
@@ -108,7 +120,11 @@ class Flagsmith:
         self.default_flag_handler = default_flag_handler
         self.enable_realtime_updates = enable_realtime_updates
         self._analytics_processor: typing.Optional[AnalyticsProcessor] = None
-        self._evaluation_context: typing.Optional[SDKEvaluationContext] = None
+        self._pipeline_analytics_processor: typing.Optional[
+            PipelineAnalyticsProcessor
+        ] = None
+        self.__evaluation_context: typing.Optional[SDKEvaluationContext] = None
+        self._segment_overrides_index: SegmentOverridesIndex = {}
         self._environment_updated_at: typing.Optional[datetime] = None
 
         # argument validation
@@ -170,10 +186,28 @@ class Flagsmith:
 
                 self._initialise_local_evaluation()
 
-            if enable_analytics:
-                self._analytics_processor = AnalyticsProcessor(
-                    environment_key, self.api_url, timeout=self.request_timeout_seconds
-                )
+            self._initialise_analytics(
+                environment_key=environment_key,
+                enable_analytics=enable_analytics,
+                pipeline_analytics_config=pipeline_analytics_config,
+            )
+
+    def _initialise_analytics(
+        self,
+        environment_key: str,
+        enable_analytics: bool,
+        pipeline_analytics_config: typing.Optional[PipelineAnalyticsConfig],
+    ) -> None:
+        if enable_analytics:
+            self._analytics_processor = AnalyticsProcessor(
+                environment_key, self.api_url, timeout=self.request_timeout_seconds
+            )
+        if pipeline_analytics_config:
+            self._pipeline_analytics_processor = PipelineAnalyticsProcessor(
+                config=pipeline_analytics_config,
+                environment_key=environment_key,
+            )
+            self._pipeline_analytics_processor.start()
 
     def _initialise_local_evaluation(self) -> None:
         # To ensure that the environment is set before allowing subsequent
@@ -290,6 +324,25 @@ class Flagsmith:
 
         return map_segment_results_to_identity_segments(evaluation_result["segments"])
 
+    def track_event(
+        self,
+        event_name: str,
+        identity_identifier: typing.Optional[str] = None,
+        traits: typing.Optional[TraitMapping] = None,
+        metadata: typing.Optional[typing.Dict[str, typing.Any]] = None,
+    ) -> None:
+        if not self._pipeline_analytics_processor:
+            raise ValueError(
+                "Pipeline analytics is not configured. "
+                "Provide pipeline_analytics_config to use track_event."
+            )
+        self._pipeline_analytics_processor.record_custom_event(
+            event_name=event_name,
+            identity_identifier=identity_identifier,
+            traits=resolve_trait_values(traits),
+            metadata=metadata,
+        )
+
     def update_environment(self) -> None:
         try:
             environment_data = self._get_json_response(
@@ -310,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,
@@ -345,6 +418,7 @@ class Flagsmith:
             evaluation_result=evaluation_result,
             analytics_processor=self._analytics_processor,
             default_flag_handler=self.default_flag_handler,
+            pipeline_analytics_processor=self._pipeline_analytics_processor,
         )
 
     def _get_identity_flags_from_document(
@@ -360,14 +434,17 @@ 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,
+            identity_identifier=identifier,
+            traits=resolve_trait_values(traits),
         )
 
     def _get_environment_flags_from_api(self) -> Flags:
@@ -379,6 +456,7 @@ class Flagsmith:
                 api_flags=json_response,
                 analytics_processor=self._analytics_processor,
                 default_flag_handler=self.default_flag_handler,
+                pipeline_analytics_processor=self._pipeline_analytics_processor,
             )
         except FlagsmithAPIError:
             if self.offline_handler:
@@ -411,6 +489,9 @@ class Flagsmith:
                 api_flags=json_response["flags"],
                 analytics_processor=self._analytics_processor,
                 default_flag_handler=self.default_flag_handler,
+                pipeline_analytics_processor=self._pipeline_analytics_processor,
+                identity_identifier=identifier,
+                traits=resolve_trait_values(traits),
             )
         except FlagsmithAPIError:
             if self.offline_handler:
@@ -443,3 +524,6 @@ class Flagsmith:
 
         if hasattr(self, "event_stream_thread"):
             self.event_stream_thread.stop()
+
+        if self._pipeline_analytics_processor:
+            self._pipeline_analytics_processor.stop()

{flagsmith-5.1.1 → flagsmith-5.3.0}/flagsmith/mappers.py

@@ -12,7 +12,6 @@ from flag_engine.context.types import (
     StrValueSegmentCondition,
 )
 from flag_engine.result.types import SegmentResult
-from flag_engine.segments.types import ContextValue
 
 from flagsmith.api.types import (
     EnvironmentModel,
@@ -26,7 +25,7 @@ from flagsmith.types import (
     SDKEvaluationContext,
     SegmentMetadata,
     StreamEvent,
-    TraitConfig,
+    TraitMapping,
 )
 from flagsmith.utils.datetime import fromisoformat
 
@@ -75,31 +74,27 @@ def map_environment_document_to_environment_updated_at(
     return updated_at.astimezone(tz=timezone.utc)
 
 
+def resolve_trait_values(
+    traits: typing.Optional[TraitMapping],
+) -> typing.Optional[typing.Dict[str, typing.Any]]:
+    if not traits:
+        return None
+    return {
+        key: (val["value"] if isinstance(val, dict) else val)
+        for key, val in traits.items()
+    }
+
+
 def map_context_and_identity_data_to_context(
     context: SDKEvaluationContext,
     identifier: str,
-    traits: typing.Optional[
-        typing.Mapping[
-            str,
-            typing.Union[
-                ContextValue,
-                TraitConfig,
-            ],
-        ]
-    ],
+    traits: typing.Optional[TraitMapping] = None,
 ) -> SDKEvaluationContext:
     return {
         **context,
         "identity": {
             "identifier": identifier,
-            "traits": {
-                trait_key: (
-                    trait_value_or_config["value"]
-                    if isinstance(trait_value_or_config, dict)
-                    else trait_value_or_config
-                )
-                for trait_key, trait_value_or_config in (traits or {}).items()
-            },
+            "traits": resolve_trait_values(traits) or {},
         },
     }
 

flagsmith-5.3.0/flagsmith/models.py

@@ -0,0 +1,299 @@
+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 (
+    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
+class BaseFlag:
+    enabled: bool
+    value: typing.Union[str, int, float, bool, None]
+
+
+@dataclass
+class DefaultFlag(BaseFlag):
+    is_default: bool = field(default=True)
+
+
+@dataclass
+class Flag(BaseFlag):
+    feature_id: int
+    feature_name: str
+    is_default: bool = field(default=False)
+
+    @classmethod
+    def from_evaluation_result(
+        cls,
+        flag_result: SDKFlagResult,
+    ) -> Flag:
+        if metadata := flag_result.get("metadata"):
+            return Flag(
+                enabled=flag_result["enabled"],
+                value=flag_result["value"],
+                feature_name=flag_result["name"],
+                feature_id=metadata["id"],
+            )
+        raise ValueError(
+            "FlagResult metadata is missing. Cannot create Flag instance. "
+            "This means a bug in the SDK, please report it."
+        )
+
+    @classmethod
+    def from_api_flag(cls, flag_data: typing.Mapping[str, typing.Any]) -> Flag:
+        return Flag(
+            enabled=flag_data["enabled"],
+            value=flag_data["feature_state_value"],
+            feature_name=flag_data["feature"]["name"],
+            feature_id=flag_data["feature"]["id"],
+        )
+
+
+@dataclass
+class Flags:
+    flags: typing.Dict[str, Flag] = field(default_factory=dict)
+    default_flag_handler: typing.Optional[typing.Callable[[str], DefaultFlag]] = None
+    _analytics_processor: typing.Optional[AnalyticsProcessor] = None
+    _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(
+        cls,
+        evaluation_result: SDKEvaluationResult,
+        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:
+        return cls(
+            flags={
+                flag_name: flag
+                for flag_name, flag_result in evaluation_result["flags"].items()
+                if (flag := Flag.from_evaluation_result(flag_result))
+            },
+            default_flag_handler=default_flag_handler,
+            _analytics_processor=analytics_processor,
+            _pipeline_analytics_processor=pipeline_analytics_processor,
+            _identity_identifier=identity_identifier,
+            _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,
+        api_flags: typing.Sequence[typing.Mapping[str, typing.Any]],
+        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:
+        flags = {
+            flag_data["feature"]["name"]: Flag.from_api_flag(flag_data)
+            for flag_data in api_flags
+        }
+
+        return cls(
+            flags=flags,
+            default_flag_handler=default_flag_handler,
+            _analytics_processor=analytics_processor,
+            _pipeline_analytics_processor=pipeline_analytics_processor,
+            _identity_identifier=identity_identifier,
+            _traits=traits,
+        )
+
+    def all_flags(self) -> typing.List[Flag]:
+        """
+        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:
+        """
+        Check whether a given feature is enabled.
+
+        :param feature_name: the name of the feature to check if enabled.
+        :return: Boolean representing the enabled state of a given feature.
+        :raises FlagsmithClientError: if feature doesn't exist
+        """
+        return self.get_flag(feature_name).enabled
+
+    def get_feature_value(self, feature_name: str) -> typing.Any:
+        """
+        Get the value of a particular feature.
+
+        :param feature_name: the name of the feature to retrieve the value of.
+        :return: the value of the given feature.
+        :raises FlagsmithClientError: if feature doesn't exist
+        """
+        return self.get_flag(feature_name).value
+
+    def get_flag(self, feature_name: str) -> typing.Union[DefaultFlag, Flag]:
+        """
+        Get a specific flag given the feature name.
+
+        :param feature_name: the name of the feature to retrieve the flag for.
+        :return: DefaultFlag | Flag object.
+        :raises FlagsmithClientError: if feature doesn't exist
+        """
+        try:
+            flag = self.flags[feature_name]
+        except KeyError:
+            # 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)
+            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)
+
+        if self._pipeline_analytics_processor and hasattr(flag, "feature_name"):
+            self._pipeline_analytics_processor.record_evaluation_event(
+                flag_key=flag.feature_name,
+                enabled=flag.enabled,
+                value=flag.value,
+                identity_identifier=self._identity_identifier,
+                traits=self._traits,
+            )
+
+        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:
+    id: int
+    name: str

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "flagsmith"
-version = "5.1.1"
+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"

flagsmith-5.1.1/flagsmith/__init__.py

@@ -1,5 +0,0 @@
-from flagsmith import webhooks
-from flagsmith.flagsmith import Flagsmith
-from flagsmith.version import __version__
-
-__all__ = ("Flagsmith", "webhooks", "__version__")

flagsmith-5.1.1/flagsmith/analytics.py

@@ -1,62 +0,0 @@
-import json
-import typing
-from datetime import datetime
-
-from requests_futures.sessions import FuturesSession  # type: ignore
-
-ANALYTICS_ENDPOINT: typing.Final[str] = "analytics/flags/"
-
-# Used to control how often we send data(in seconds)
-ANALYTICS_TIMER: typing.Final[int] = 10
-
-session = FuturesSession(max_workers=4)
-
-
-class AnalyticsProcessor:
-    """
-    AnalyticsProcessor is used to track how often individual Flags are evaluated within
-    the Flagsmith SDK. Docs: https://docs.flagsmith.com/advanced-use/flag-analytics.
-    """
-
-    def __init__(
-        self, environment_key: str, base_api_url: str, timeout: typing.Optional[int] = 3
-    ):
-        """
-        Initialise the AnalyticsProcessor to handle sending analytics on flag usage to
-        the Flagsmith API.
-
-        :param environment_key: environment key obtained from the Flagsmith UI
-        :param base_api_url: base api url to override when using self hosted version
-        :param timeout: used to tell requests to stop waiting for a response after a
-            given number of seconds
-        """
-        self.analytics_endpoint = base_api_url + ANALYTICS_ENDPOINT
-        self.environment_key = environment_key
-        self._last_flushed = datetime.now()
-        self.analytics_data: typing.MutableMapping[str, typing.Any] = {}
-        self.timeout = timeout or 3
-
-    def flush(self) -> None:
-        """
-        Sends all the collected data to the api asynchronously and resets the timer
-        """
-
-        if not self.analytics_data:
-            return
-        session.post(
-            self.analytics_endpoint,
-            data=json.dumps(self.analytics_data),
-            timeout=self.timeout,
-            headers={
-                "X-Environment-Key": self.environment_key,
-                "Content-Type": "application/json",
-            },
-        )
-
-        self.analytics_data.clear()
-        self._last_flushed = datetime.now()
-
-    def track_feature(self, feature_name: str) -> None:
-        self.analytics_data[feature_name] = self.analytics_data.get(feature_name, 0) + 1
-        if (datetime.now() - self._last_flushed).seconds > ANALYTICS_TIMER:
-            self.flush()

flagsmith-5.1.1/flagsmith/models.py

@@ -1,150 +0,0 @@
-from __future__ import annotations
-
-import typing
-from dataclasses import dataclass, field
-
-from flagsmith.analytics import AnalyticsProcessor
-from flagsmith.exceptions import FlagsmithFeatureDoesNotExistError
-from flagsmith.types import SDKEvaluationResult, SDKFlagResult
-
-
-@dataclass
-class BaseFlag:
-    enabled: bool
-    value: typing.Union[str, int, float, bool, None]
-
-
-@dataclass
-class DefaultFlag(BaseFlag):
-    is_default: bool = field(default=True)
-
-
-@dataclass
-class Flag(BaseFlag):
-    feature_id: int
-    feature_name: str
-    is_default: bool = field(default=False)
-
-    @classmethod
-    def from_evaluation_result(
-        cls,
-        flag_result: SDKFlagResult,
-    ) -> Flag:
-        if metadata := flag_result.get("metadata"):
-            return Flag(
-                enabled=flag_result["enabled"],
-                value=flag_result["value"],
-                feature_name=flag_result["name"],
-                feature_id=metadata["id"],
-            )
-        raise ValueError(
-            "FlagResult metadata is missing. Cannot create Flag instance. "
-            "This means a bug in the SDK, please report it."
-        )
-
-    @classmethod
-    def from_api_flag(cls, flag_data: typing.Mapping[str, typing.Any]) -> Flag:
-        return Flag(
-            enabled=flag_data["enabled"],
-            value=flag_data["feature_state_value"],
-            feature_name=flag_data["feature"]["name"],
-            feature_id=flag_data["feature"]["id"],
-        )
-
-
-@dataclass
-class Flags:
-    flags: typing.Dict[str, Flag] = field(default_factory=dict)
-    default_flag_handler: typing.Optional[typing.Callable[[str], DefaultFlag]] = None
-    _analytics_processor: typing.Optional[AnalyticsProcessor] = None
-
-    @classmethod
-    def from_evaluation_result(
-        cls,
-        evaluation_result: SDKEvaluationResult,
-        analytics_processor: typing.Optional[AnalyticsProcessor],
-        default_flag_handler: typing.Optional[typing.Callable[[str], DefaultFlag]],
-    ) -> Flags:
-        return cls(
-            flags={
-                flag_name: flag
-                for flag_name, flag_result in evaluation_result["flags"].items()
-                if (flag := Flag.from_evaluation_result(flag_result))
-            },
-            default_flag_handler=default_flag_handler,
-            _analytics_processor=analytics_processor,
-        )
-
-    @classmethod
-    def from_api_flags(
-        cls,
-        api_flags: typing.Sequence[typing.Mapping[str, typing.Any]],
-        analytics_processor: typing.Optional[AnalyticsProcessor],
-        default_flag_handler: typing.Optional[typing.Callable[[str], DefaultFlag]],
-    ) -> Flags:
-        flags = {
-            flag_data["feature"]["name"]: Flag.from_api_flag(flag_data)
-            for flag_data in api_flags
-        }
-
-        return cls(
-            flags=flags,
-            default_flag_handler=default_flag_handler,
-            _analytics_processor=analytics_processor,
-        )
-
-    def all_flags(self) -> typing.List[Flag]:
-        """
-        Get a list of all Flag objects.
-
-        :return: list of Flag objects.
-        """
-        return list(self.flags.values())
-
-    def is_feature_enabled(self, feature_name: str) -> bool:
-        """
-        Check whether a given feature is enabled.
-
-        :param feature_name: the name of the feature to check if enabled.
-        :return: Boolean representing the enabled state of a given feature.
-        :raises FlagsmithClientError: if feature doesn't exist
-        """
-        return self.get_flag(feature_name).enabled
-
-    def get_feature_value(self, feature_name: str) -> typing.Any:
-        """
-        Get the value of a particular feature.
-
-        :param feature_name: the name of the feature to retrieve the value of.
-        :return: the value of the given feature.
-        :raises FlagsmithClientError: if feature doesn't exist
-        """
-        return self.get_flag(feature_name).value
-
-    def get_flag(self, feature_name: str) -> typing.Union[DefaultFlag, Flag]:
-        """
-        Get a specific flag given the feature name.
-
-        :param feature_name: the name of the feature to retrieve the flag for.
-        :return: DefaultFlag | Flag object.
-        :raises FlagsmithClientError: if feature doesn't exist
-        """
-        try:
-            flag = self.flags[feature_name]
-        except KeyError:
-            if self.default_flag_handler:
-                return self.default_flag_handler(feature_name)
-            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)
-
-        return flag
-
-
-@dataclass
-class Segment:
-    id: int
-    name: str