flagsmith 6.0.0__tar.gz → 6.2.0__tar.gz

{flagsmith-6.0.0 → flagsmith-6.2.0}/PKG-INFO

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

{flagsmith-6.0.0 → flagsmith-6.2.0}/flagsmith/analytics.py

@@ -31,7 +31,11 @@ class AnalyticsProcessor:
     """
 
     def __init__(
-        self, environment_key: str, base_api_url: str, timeout: typing.Optional[int] = 3
+        self,
+        environment_key: str,
+        base_api_url: str,
+        timeout: typing.Optional[int] = 3,
+        analytics_url: typing.Optional[str] = None,
     ):
         """
         Initialise the AnalyticsProcessor to handle sending analytics on flag usage to
@@ -41,8 +45,13 @@ class AnalyticsProcessor:
         :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
+        :param analytics_url: full URL of the flag analytics endpoint, used to override
+            the default ``<base_api_url>/analytics/flags/``. Intended for deployments
+            where flag evaluation traffic and analytics traffic must go to different
+            hosts (for example, evaluating through the Edge Proxy while sending
+            analytics to the core API).
         """
-        self.analytics_endpoint = base_api_url + ANALYTICS_ENDPOINT
+        self.analytics_endpoint = analytics_url or (base_api_url + ANALYTICS_ENDPOINT)
         self.environment_key = environment_key
         self._last_flushed = datetime.now()
         self.analytics_data: typing.MutableMapping[str, typing.Any] = {}
@@ -74,6 +83,12 @@ class AnalyticsProcessor:
             self.flush()
 
 
+class ExposureKey(typing.NamedTuple):
+    feature_name: typing.Optional[str]
+    identifier: typing.Optional[str]
+    value: typing.Optional[str]
+
+
 @dataclass
 class EventProcessorConfig:
     events_api_url: str = DEFAULT_EVENT_API_URL
@@ -102,6 +117,7 @@ class EventProcessor:
         self._flush_interval_seconds = config.flush_interval_seconds
 
         self._buffer: typing.List[typing.Dict[str, typing.Any]] = []
+        self._buffered_exposure_keys: typing.Set[ExposureKey] = set()
         self._lock = threading.Lock()
         self._timer: typing.Optional[threading.Timer] = None
 
@@ -150,6 +166,24 @@ class EventProcessor:
     ) -> None:
         should_flush = False
         with self._lock:
+            if event == FLAG_EXPOSURE_EVENT:
+                # An exposure is defined by who saw which variant of which
+                # feature; equal exposures within one flush interval add no
+                # information, so only the first is buffered.
+                exposure_key = ExposureKey(
+                    feature_name=feature_name,
+                    identifier=identifier,
+                    value=str(value) if value is not None else None,
+                )
+                if exposure_key in self._buffered_exposure_keys:
+                    logger.debug(
+                        "Skipping duplicate %s event for feature %s, identifier %s",
+                        FLAG_EXPOSURE_EVENT,
+                        feature_name,
+                        identifier,
+                    )
+                    return
+                self._buffered_exposure_keys.add(exposure_key)
             self._buffer.append(
                 {
                     "event": event,
@@ -173,6 +207,7 @@ class EventProcessor:
                 return
             events = self._buffer
             self._buffer = []
+            self._buffered_exposure_keys.clear()
 
         payload = json.dumps({"events": events})
         try:

{flagsmith-6.0.0 → flagsmith-6.2.0}/flagsmith/flagsmith.py

@@ -70,6 +70,7 @@ class Flagsmith:
         environment_key: typing.Optional[str] = None,
         api_url: typing.Optional[str] = None,
         realtime_api_url: typing.Optional[str] = None,
+        analytics_url: typing.Optional[str] = None,
         custom_headers: typing.Optional[typing.Dict[str, typing.Any]] = None,
         request_timeout_seconds: typing.Optional[int] = 10,
         enable_local_evaluation: bool = False,
@@ -92,6 +93,11 @@ class Flagsmith:
             Required unless offline_mode is True.
         :param api_url: Override the URL of the Flagsmith API to communicate with
         :param realtime_api_url: Override the URL of the Flagsmith real-time API
+        :param analytics_url: Override the URL used for flag analytics requests when
+            enable_analytics is True. When unset, analytics are posted to
+            ``<api_url>/analytics/flags/``. Set this when api_url points at a host that
+            does not handle analytics (for example, the Edge Proxy) so analytics can be
+            sent directly to the core Flagsmith API.
         :param custom_headers: Additional headers to add to requests made to the
             Flagsmith API
         :param request_timeout_seconds: Number of seconds to wait for a request to
@@ -172,14 +178,12 @@ class Flagsmith:
             self.session.proxies.update(proxies or {})
             retries = retries or Retry(total=3, backoff_factor=0.1)
 
-            api_url = api_url or DEFAULT_API_URL
-            self.api_url = api_url if api_url.endswith("/") else f"{api_url}/"
-
-            realtime_api_url = realtime_api_url or DEFAULT_REALTIME_API_URL
-            self.realtime_api_url = (
-                realtime_api_url
-                if realtime_api_url.endswith("/")
-                else f"{realtime_api_url}/"
+            self.api_url = self._ensure_trailing_slash(api_url or DEFAULT_API_URL)
+            self.realtime_api_url = self._ensure_trailing_slash(
+                realtime_api_url or DEFAULT_REALTIME_API_URL
+            )
+            self.analytics_url = (
+                self._ensure_trailing_slash(analytics_url) if analytics_url else None
             )
 
             self.request_timeout_seconds = request_timeout_seconds
@@ -201,6 +205,7 @@ class Flagsmith:
             self._initialise_analytics(
                 environment_key=environment_key,
                 enable_analytics=enable_analytics,
+                analytics_url=self.analytics_url,
             )
             self._initialise_events(
                 environment_key=environment_key,
@@ -208,14 +213,22 @@ class Flagsmith:
                 event_processor_config=event_processor_config,
             )
 
+    @staticmethod
+    def _ensure_trailing_slash(url: str) -> str:
+        return url if url.endswith("/") else f"{url}/"
+
     def _initialise_analytics(
         self,
         environment_key: str,
         enable_analytics: bool,
+        analytics_url: typing.Optional[str] = None,
     ) -> None:
         if enable_analytics:
             self._analytics_processor = AnalyticsProcessor(
-                environment_key, self.api_url, timeout=self.request_timeout_seconds
+                environment_key,
+                self.api_url,
+                timeout=self.request_timeout_seconds,
+                analytics_url=analytics_url,
             )
 
     def _initialise_events(
@@ -355,19 +368,38 @@ class Flagsmith:
         """
         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`) or when the feature is disabled, to keep
-        experimentation data clean.
+        The exposure event's ``value`` is the flag's variant key. It is only
+        sent when the flag exists, is enabled and carries a variant; any
+        other outcome is logged and skipped to keep experimentation data
+        clean. A `DefaultFlag` served via the `default_flag_handler` counts
+        as the feature not existing.
         """
         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 isinstance(flag, Flag) and flag.enabled:
+        if not isinstance(flag, Flag):
+            logger.debug(
+                "Not sending %s for feature %s: feature not found.",
+                FLAG_EXPOSURE_EVENT,
+                feature_name,
+            )
+        elif not flag.enabled:
+            logger.debug(
+                "Not sending %s for feature %s: feature is disabled.",
+                FLAG_EXPOSURE_EVENT,
+                feature_name,
+            )
+        elif flag.variant is None:
+            logger.debug(
+                "Not sending %s for feature %s: flag has no variant.",
+                FLAG_EXPOSURE_EVENT,
+                feature_name,
+            )
+        else:
             self.track_exposure_event(
                 feature_name=feature_name,
                 identifier=identifier,
-                value=flag.variant if flag.variant is not None else flag.value,
+                value=flag.variant,
                 traits=traits,
             )
         return flag
@@ -405,6 +437,14 @@ class Flagsmith:
     ) -> None:
         if not self._event_processor:
             raise ValueError("Events must be enabled to track exposure events.")
+        if not identifier:
+            logger.warning(
+                "Not sending %s for feature %s: an exposure requires an"
+                " identifier to reconcile with conversion events.",
+                FLAG_EXPOSURE_EVENT,
+                feature_name,
+            )
+            return
         self._event_processor.track_exposure_event(
             feature_name=feature_name,
             identifier=identifier,

{flagsmith-6.0.0 → flagsmith-6.2.0}/flagsmith/models.py

@@ -52,6 +52,7 @@ class Flag(BaseFlag):
     feature_id: int
     feature_name: str
     variant: typing.Optional[str] = None
+    reason: typing.Optional[str] = None
     is_default: bool = field(default=False)
 
     @classmethod
@@ -66,6 +67,7 @@ class Flag(BaseFlag):
                 feature_name=flag_result["name"],
                 feature_id=metadata["id"],
                 variant=flag_result.get("variant"),
+                reason=flag_result["reason"],
             )
         raise ValueError(
             "FlagResult metadata is missing. Cannot create Flag instance. "
@@ -80,6 +82,7 @@ class Flag(BaseFlag):
             feature_name=flag_data["feature"]["name"],
             feature_id=flag_data["feature"]["id"],
             variant=flag_data.get("variant"),
+            reason=flag_data.get("reason"),
         )
 
 

{flagsmith-6.0.0 → flagsmith-6.2.0}/pyproject.toml

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