flagsmith 5.3.0__tar.gz → 5.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flagsmith
-Version: 5.3.0
+Version: 5.4.0
 Summary: Flagsmith Python SDK
 License: BSD3
 License-File: LICENSE

flagsmith-5.4.0/flagsmith/__init__.py

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

{flagsmith-5.3.0 → flagsmith-5.4.0}/flagsmith/analytics.py

@@ -2,7 +2,6 @@ import atexit
 import json
 import logging
 import threading
-import time
 import typing
 from dataclasses import dataclass
 from datetime import datetime
@@ -18,6 +17,10 @@ ANALYTICS_ENDPOINT: typing.Final[str] = "analytics/flags/"
 # Used to control how often we send data(in seconds)
 ANALYTICS_TIMER: typing.Final[int] = 10
 
+FLAG_EXPOSURE_EVENT: typing.Final[str] = "$flag_exposure"
+
+DEFAULT_EVENT_API_URL: typing.Final[str] = "https://events.api.flagsmith.com/"
+
 session = FuturesSession(max_workers=4)
 
 
@@ -72,92 +75,90 @@ class AnalyticsProcessor:
 
 
 @dataclass
-class PipelineAnalyticsConfig:
-    analytics_server_url: str
+class EventProcessorConfig:
+    events_api_url: str = DEFAULT_EVENT_API_URL
     max_buffer_items: int = 1000
     flush_interval_seconds: float = 10.0
 
 
-class PipelineAnalyticsProcessor:
+class EventProcessor:
     """
-    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.
+    Buffered event processor that batches custom events and POSTs them to the
+    Flagsmith event endpoint. Flushes on a background timer or when the buffer
+    fills.
     """
 
     def __init__(
         self,
-        config: PipelineAnalyticsConfig,
+        config: EventProcessorConfig,
         environment_key: str,
     ) -> None:
-        url = config.analytics_server_url
+        url = config.events_api_url
         if not url.endswith("/"):
             url = f"{url}/"
-        self._batch_endpoint = f"{url}v1/analytics/batch"
+        self._batch_endpoint = f"{url}v1/events"
         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(
+    def track_event(
         self,
-        flag_key: str,
-        enabled: bool,
-        value: typing.Any,
-        identity_identifier: typing.Optional[str] = None,
+        event: str,
+        identifier: typing.Optional[str] = None,
+        value: typing.Optional[typing.Union[str, int, float, bool]] = None,
         traits: typing.Optional[typing.Dict[str, typing.Any]] = None,
+        metadata: 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()
+        self._buffer_event(
+            event=event,
+            feature_name=None,
+            identifier=identifier,
+            value=value,
+            traits=traits,
+            metadata=metadata,
+        )
 
-    def record_custom_event(
+    def track_exposure_event(
         self,
-        event_name: str,
-        identity_identifier: typing.Optional[str] = None,
+        feature_name: str,
+        identifier: typing.Optional[str] = None,
+        value: typing.Optional[typing.Union[str, int, float, bool]] = None,
         traits: typing.Optional[typing.Dict[str, typing.Any]] = None,
         metadata: typing.Optional[typing.Dict[str, typing.Any]] = None,
     ) -> None:
-        should_flush = False
+        self._buffer_event(
+            event=FLAG_EXPOSURE_EVENT,
+            feature_name=feature_name,
+            identifier=identifier,
+            value=value,
+            traits=traits,
+            metadata=metadata,
+        )
 
+    def _buffer_event(
+        self,
+        event: str,
+        feature_name: typing.Optional[str],
+        identifier: typing.Optional[str],
+        value: typing.Optional[typing.Union[str, int, float, bool]],
+        traits: typing.Optional[typing.Dict[str, typing.Any]],
+        metadata: typing.Optional[typing.Dict[str, typing.Any]],
+    ) -> 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,
+                    "event": event,
+                    "feature_name": feature_name,
+                    "identifier": identifier,
+                    "value": str(value) if value is not None else None,
                     "traits": dict(traits) if traits else None,
                     "metadata": {**(metadata or {}), "sdk_version": __version__},
+                    "timestamp": int(datetime.now().timestamp() * 1000),
                 }
             )
             if len(self._buffer) >= self._max_buffer:
@@ -172,11 +173,8 @@ class PipelineAnalyticsProcessor:
                 return
             events = self._buffer
             self._buffer = []
-            self._dedup_keys.clear()
 
-        payload = json.dumps(
-            {"events": events, "environment_key": self._environment_key}
-        )
+        payload = json.dumps({"events": events})
         try:
             future = session.post(
                 self._batch_endpoint,

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

@@ -9,9 +9,10 @@ from requests.adapters import HTTPAdapter
 from urllib3 import Retry
 
 from flagsmith.analytics import (
+    FLAG_EXPOSURE_EVENT,
     AnalyticsProcessor,
-    PipelineAnalyticsConfig,
-    PipelineAnalyticsProcessor,
+    EventProcessor,
+    EventProcessorConfig,
 )
 from flagsmith.exceptions import FlagsmithAPIError, FlagsmithClientError
 from flagsmith.mappers import (
@@ -23,6 +24,7 @@ from flagsmith.mappers import (
 )
 from flagsmith.models import (
     DefaultFlag,
+    Flag,
     Flags,
     Segment,
     SegmentOverridesIndex,
@@ -74,7 +76,8 @@ 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,
+        enable_events: bool = False,
+        event_processor_config: typing.Optional[EventProcessorConfig] = None,
         default_flag_handler: typing.Optional[
             typing.Callable[[str], DefaultFlag]
         ] = None,
@@ -100,6 +103,12 @@ class Flagsmith:
             Flagsmith API
         :param enable_analytics: if enabled, sends additional requests to the Flagsmith
             API to power flag analytics charts
+        :param enable_events: if enabled, starts an event processor that buffers
+            and sends events (custom and flag-exposure) to the Flagsmith events
+            API, powering experimentation analytics.
+        :param event_processor_config: optional configuration for the event
+            processor (URL override for self-hosted, buffer/flush tuning). Only
+            valid when ``enable_events=True``.
         :param default_flag_handler: callable which will be used in the case where
             flags cannot be retrieved from the API or a non-existent feature is
             requested
@@ -120,9 +129,7 @@ class Flagsmith:
         self.default_flag_handler = default_flag_handler
         self.enable_realtime_updates = enable_realtime_updates
         self._analytics_processor: typing.Optional[AnalyticsProcessor] = None
-        self._pipeline_analytics_processor: typing.Optional[
-            PipelineAnalyticsProcessor
-        ] = None
+        self._event_processor: typing.Optional[EventProcessor] = None
         self.__evaluation_context: typing.Optional[SDKEvaluationContext] = None
         self._segment_overrides_index: SegmentOverridesIndex = {}
         self._environment_updated_at: typing.Optional[datetime] = None
@@ -140,6 +147,11 @@ class Flagsmith:
                 "Can only use realtime updates when running in local evaluation mode."
             )
 
+        if event_processor_config is not None and not enable_events:
+            raise ValueError(
+                "event_processor_config can only be set when enable_events=True."
+            )
+
         if self.offline_handler:
             self._evaluation_context = map_environment_document_to_context(
                 self.offline_handler.get_environment()
@@ -189,25 +201,35 @@ class Flagsmith:
             self._initialise_analytics(
                 environment_key=environment_key,
                 enable_analytics=enable_analytics,
-                pipeline_analytics_config=pipeline_analytics_config,
+            )
+            self._initialise_events(
+                environment_key=environment_key,
+                enable_events=enable_events,
+                event_processor_config=event_processor_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,
+
+    def _initialise_events(
+        self,
+        environment_key: str,
+        enable_events: bool,
+        event_processor_config: typing.Optional[EventProcessorConfig],
+    ) -> None:
+        if enable_events:
+            self._event_processor = EventProcessor(
+                config=event_processor_config or EventProcessorConfig(),
                 environment_key=environment_key,
             )
-            self._pipeline_analytics_processor.start()
+            self._event_processor.start()
 
     def _initialise_local_evaluation(self) -> None:
         # To ensure that the environment is set before allowing subsequent
@@ -324,21 +346,68 @@ class Flagsmith:
 
         return map_segment_results_to_identity_segments(evaluation_result["segments"])
 
+    def get_experiment_flag(
+        self,
+        feature_name: str,
+        identifier: str,
+        traits: typing.Optional[TraitMapping] = None,
+    ) -> typing.Union[DefaultFlag, Flag]:
+        """
+        Resolve a flag for an identity and record an exposure event.
+
+        Skips the exposure event when the resolved flag is a `DefaultFlag`
+        (i.e. the feature was not present and was served via the
+        `default_flag_handler`), to keep experimentation data clean.
+        """
+        if not self._event_processor:
+            raise ValueError("Events must be enabled to use experiment flags.")
+        flag = self.get_identity_flags(identifier, traits).get_flag(feature_name)
+        if not flag.is_default:
+            self.track_exposure_event(
+                feature_name=feature_name,
+                identifier=identifier,
+                value=flag.value,
+                traits=traits,
+            )
+        return flag
+
     def track_event(
         self,
-        event_name: str,
-        identity_identifier: typing.Optional[str] = None,
+        event: str,
+        identifier: typing.Optional[str] = None,
+        value: typing.Optional[typing.Union[str, int, float, bool]] = None,
         traits: typing.Optional[TraitMapping] = None,
         metadata: typing.Optional[typing.Dict[str, typing.Any]] = None,
     ) -> None:
-        if not self._pipeline_analytics_processor:
+        if not self._event_processor:
+            raise ValueError("Events must be enabled to track events.")
+        if event.startswith("$") and event != FLAG_EXPOSURE_EVENT:
             raise ValueError(
-                "Pipeline analytics is not configured. "
-                "Provide pipeline_analytics_config to use track_event."
+                f'Event name "{event}" uses the reserved "$" prefix '
+                "but is not a known system event."
             )
-        self._pipeline_analytics_processor.record_custom_event(
-            event_name=event_name,
-            identity_identifier=identity_identifier,
+        self._event_processor.track_event(
+            event=event,
+            identifier=identifier,
+            value=value,
+            traits=resolve_trait_values(traits),
+            metadata=metadata,
+        )
+
+    def track_exposure_event(
+        self,
+        feature_name: str,
+        identifier: typing.Optional[str] = None,
+        value: typing.Optional[typing.Union[str, int, float, bool]] = None,
+        traits: typing.Optional[TraitMapping] = None,
+        metadata: typing.Optional[typing.Dict[str, typing.Any]] = None,
+    ) -> None:
+        if not self._event_processor:
+            raise ValueError("Events must be enabled to track exposure events.")
+        self._event_processor.track_exposure_event(
+            feature_name=feature_name,
+            identifier=identifier,
+            value=value,
             traits=resolve_trait_values(traits),
             metadata=metadata,
         )
@@ -418,7 +487,6 @@ 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(
@@ -442,9 +510,6 @@ class Flagsmith:
             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:
@@ -456,7 +521,6 @@ 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:
@@ -489,9 +553,6 @@ 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:
@@ -525,5 +586,5 @@ class Flagsmith:
         if hasattr(self, "event_stream_thread"):
             self.event_stream_thread.stop()
 
-        if self._pipeline_analytics_processor:
-            self._pipeline_analytics_processor.stop()
+        if self._event_processor:
+            self._event_processor.stop()

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

@@ -6,7 +6,7 @@ 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.analytics import AnalyticsProcessor
 from flagsmith.exceptions import FlagsmithFeatureDoesNotExistError
 from flagsmith.types import (
     FeatureMetadata,
@@ -85,9 +85,6 @@ 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
@@ -103,11 +100,6 @@ class Flags:
         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={
@@ -117,9 +109,6 @@ class Flags:
             },
             default_flag_handler=default_flag_handler,
             _analytics_processor=analytics_processor,
-            _pipeline_analytics_processor=pipeline_analytics_processor,
-            _identity_identifier=identity_identifier,
-            _traits=traits,
         )
 
     @classmethod
@@ -129,11 +118,6 @@ class Flags:
         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.
 
@@ -146,9 +130,6 @@ class Flags:
             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,
         )
@@ -159,11 +140,6 @@ class Flags:
         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)
@@ -174,9 +150,6 @@ class Flags:
             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]:
@@ -252,15 +225,6 @@ class Flags:
         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:

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "flagsmith"
-version = "5.3.0"
+version = "5.4.0"
 description = "Flagsmith Python SDK"
 authors = ["Flagsmith <support@flagsmith.com>"]
 license = "BSD3"

flagsmith-5.3.0/flagsmith/__init__.py

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