posthoganalytics 6.5.0__tar.gz → 6.6.1__tar.gz

{posthoganalytics-6.5.0/posthoganalytics.egg-info → posthoganalytics-6.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: posthoganalytics
-Version: 6.5.0
+Version: 6.6.1
 Summary: Integrate PostHog into any python application.
 Home-page: https://github.com/posthog/posthog-python
 Author: Posthog

{posthoganalytics-6.5.0 → posthoganalytics-6.6.1}/posthoganalytics/client.py

@@ -44,6 +44,7 @@ from posthoganalytics.types import (
     FlagsAndPayloads,
     FlagsResponse,
     FlagValue,
+    SendFeatureFlagsOptions,
     normalize_flags_response,
     to_flags_and_payloads,
     to_payloads,
@@ -313,6 +314,7 @@ class Client(object):
         person_properties=None,
         group_properties=None,
         disable_geoip=None,
+        flag_keys_to_evaluate: Optional[list[str]] = None,
     ) -> dict[str, Union[bool, str]]:
         """
         Get feature flag variants for a user by calling decide.
@@ -323,12 +325,19 @@ class Client(object):
             person_properties: A dictionary of person properties.
             group_properties: A dictionary of group properties.
             disable_geoip: Whether to disable GeoIP for this request.
+            flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided,
+                only these flags will be evaluated, improving performance.
 
         Category:
             Feature Flags
         """
         resp_data = self.get_flags_decision(
-            distinct_id, groups, person_properties, group_properties, disable_geoip
+            distinct_id,
+            groups,
+            person_properties,
+            group_properties,
+            disable_geoip,
+            flag_keys_to_evaluate,
         )
         return to_values(resp_data) or {}
 
@@ -339,6 +348,7 @@ class Client(object):
         person_properties=None,
         group_properties=None,
         disable_geoip=None,
+        flag_keys_to_evaluate: Optional[list[str]] = None,
     ) -> dict[str, str]:
         """
         Get feature flag payloads for a user by calling decide.
@@ -349,6 +359,8 @@ class Client(object):
             person_properties: A dictionary of person properties.
             group_properties: A dictionary of group properties.
             disable_geoip: Whether to disable GeoIP for this request.
+            flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided,
+                only these flags will be evaluated, improving performance.
 
         Examples:
             ```python
@@ -359,7 +371,12 @@ class Client(object):
             Feature Flags
         """
         resp_data = self.get_flags_decision(
-            distinct_id, groups, person_properties, group_properties, disable_geoip
+            distinct_id,
+            groups,
+            person_properties,
+            group_properties,
+            disable_geoip,
+            flag_keys_to_evaluate,
         )
         return to_payloads(resp_data) or {}
 
@@ -370,6 +387,7 @@ class Client(object):
         person_properties=None,
         group_properties=None,
         disable_geoip=None,
+        flag_keys_to_evaluate: Optional[list[str]] = None,
     ) -> FlagsAndPayloads:
         """
         Get feature flags and payloads for a user by calling decide.
@@ -380,6 +398,8 @@ class Client(object):
             person_properties: A dictionary of person properties.
             group_properties: A dictionary of group properties.
             disable_geoip: Whether to disable GeoIP for this request.
+            flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided,
+                only these flags will be evaluated, improving performance.
 
         Examples:
             ```python
@@ -390,7 +410,12 @@ class Client(object):
             Feature Flags
         """
         resp = self.get_flags_decision(
-            distinct_id, groups, person_properties, group_properties, disable_geoip
+            distinct_id,
+            groups,
+            person_properties,
+            group_properties,
+            disable_geoip,
+            flag_keys_to_evaluate,
         )
         return to_flags_and_payloads(resp)
 
@@ -401,6 +426,7 @@ class Client(object):
         person_properties=None,
         group_properties=None,
         disable_geoip=None,
+        flag_keys_to_evaluate: Optional[list[str]] = None,
     ) -> FlagsResponse:
         """
         Get feature flags decision.
@@ -411,6 +437,8 @@ class Client(object):
             person_properties: A dictionary of person properties.
             group_properties: A dictionary of group properties.
             disable_geoip: Whether to disable GeoIP for this request.
+            flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided,
+                only these flags will be evaluated, improving performance.
 
         Examples:
             ```python
@@ -441,6 +469,9 @@ class Client(object):
             "geoip_disable": disable_geoip,
         }
 
+        if flag_keys_to_evaluate:
+            request_data["flag_keys_to_evaluate"] = flag_keys_to_evaluate
+
         resp_data = flags(
             self.api_key,
             self.host,
@@ -545,6 +576,7 @@ class Client(object):
                         group_properties=flag_options["group_properties"],
                         disable_geoip=disable_geoip,
                         only_evaluate_locally=True,
+                        flag_keys_to_evaluate=flag_options["flag_keys_filter"],
                     )
                 else:
                     # Default behavior - use remote evaluation
@@ -554,6 +586,7 @@ class Client(object):
                         person_properties=flag_options["person_properties"],
                         group_properties=flag_options["group_properties"],
                         disable_geoip=disable_geoip,
+                        flag_keys_to_evaluate=flag_options["flag_keys_filter"],
                     )
             except Exception as e:
                 self.log.exception(
@@ -586,7 +619,7 @@ class Client(object):
 
         return self._enqueue(msg, disable_geoip)
 
-    def _parse_send_feature_flags(self, send_feature_flags) -> dict:
+    def _parse_send_feature_flags(self, send_feature_flags) -> SendFeatureFlagsOptions:
         """
         Parse and normalize send_feature_flags parameter into a standard format.
 
@@ -594,8 +627,8 @@ class Client(object):
             send_feature_flags: Either bool or SendFeatureFlagsOptions dict
 
         Returns:
-            dict: Normalized options with keys: should_send, only_evaluate_locally,
-                  person_properties, group_properties
+            SendFeatureFlagsOptions: Normalized options with keys: should_send, only_evaluate_locally,
+                  person_properties, group_properties, flag_keys_filter
 
         Raises:
             TypeError: If send_feature_flags is not bool or dict
@@ -608,6 +641,7 @@ class Client(object):
                 ),
                 "person_properties": send_feature_flags.get("person_properties"),
                 "group_properties": send_feature_flags.get("group_properties"),
+                "flag_keys_filter": send_feature_flags.get("flag_keys_filter"),
             }
         elif isinstance(send_feature_flags, bool):
             return {
@@ -615,6 +649,7 @@ class Client(object):
                 "only_evaluate_locally": None,
                 "person_properties": None,
                 "group_properties": None,
+                "flag_keys_filter": None,
             }
         else:
             raise TypeError(
@@ -1169,6 +1204,9 @@ class Client(object):
         person_properties = person_properties or {}
         group_properties = group_properties or {}
 
+        # Create evaluation cache for flag dependencies
+        evaluation_cache: dict[str, Optional[FlagValue]] = {}
+
         if feature_flag.get("ensure_experience_continuity", False):
             raise InconclusiveMatchError("Flag has experience continuity enabled")
 
@@ -1184,12 +1222,12 @@ class Client(object):
                 self.log.warning(
                     f"[FEATURE FLAGS] Unknown group type index {aggregation_group_type_index} for feature flag {feature_flag['key']}"
                 )
-                # failover to `/decide/`
+                # failover to `/flags`
                 raise InconclusiveMatchError("Flag has unknown group type index")
 
             if group_name not in groups:
                 # Group flags are never enabled in `groups` aren't passed in
-                # don't failover to `/decide/`, since response will be the same
+                # don't failover to `/flags`, since response will be the same
                 if warn_on_unknown_groups:
                     self.log.warning(
                         f"[FEATURE FLAGS] Can't compute group feature flag: {feature_flag['key']} without group names passed in"
@@ -1202,11 +1240,20 @@ class Client(object):
 
             focused_group_properties = group_properties[group_name]
             return match_feature_flag_properties(
-                feature_flag, groups[group_name], focused_group_properties
+                feature_flag,
+                groups[group_name],
+                focused_group_properties,
+                self.feature_flags_by_key,
+                evaluation_cache,
             )
         else:
             return match_feature_flag_properties(
-                feature_flag, distinct_id, person_properties, self.cohorts
+                feature_flag,
+                distinct_id,
+                person_properties,
+                self.cohorts,
+                self.feature_flags_by_key,
+                evaluation_cache,
             )
 
     def feature_enabled(
@@ -1317,7 +1364,7 @@ class Client(object):
                 )
         elif not only_evaluate_locally:
             try:
-                flag_details, request_id = self._get_feature_flag_details_from_decide(
+                flag_details, request_id = self._get_feature_flag_details_from_server(
                     key,
                     distinct_id,
                     groups,
@@ -1557,7 +1604,7 @@ class Client(object):
         )
         return feature_flag_result.payload if feature_flag_result else None
 
-    def _get_feature_flag_details_from_decide(
+    def _get_feature_flag_details_from_server(
         self,
         key: str,
         distinct_id: ID_TYPES,
@@ -1567,10 +1614,15 @@ class Client(object):
         disable_geoip: Optional[bool],
     ) -> tuple[Optional[FeatureFlag], Optional[str]]:
         """
-        Calls /decide and returns the flag details and request id
+        Calls /flags and returns the flag details and request id
         """
         resp_data = self.get_flags_decision(
-            distinct_id, groups, person_properties, group_properties, disable_geoip
+            distinct_id,
+            groups,
+            person_properties,
+            group_properties,
+            disable_geoip,
+            flag_keys_to_evaluate=[key],
         )
         request_id = resp_data.get("requestId")
         flags = resp_data.get("flags")
@@ -1686,6 +1738,7 @@ class Client(object):
         group_properties=None,
         only_evaluate_locally=False,
         disable_geoip=None,
+        flag_keys_to_evaluate: Optional[list[str]] = None,
     ) -> Optional[dict[str, Union[bool, str]]]:
         """
         Get all feature flags for a user.
@@ -1697,6 +1750,8 @@ class Client(object):
             group_properties: A dictionary of group properties.
             only_evaluate_locally: Whether to only evaluate locally.
             disable_geoip: Whether to disable GeoIP for this request.
+            flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided,
+                only these flags will be evaluated, improving performance.
 
         Examples:
             ```python
@@ -1713,6 +1768,7 @@ class Client(object):
             group_properties=group_properties,
             only_evaluate_locally=only_evaluate_locally,
             disable_geoip=disable_geoip,
+            flag_keys_to_evaluate=flag_keys_to_evaluate,
         )
 
         return response["featureFlags"]
@@ -1726,6 +1782,7 @@ class Client(object):
         group_properties=None,
         only_evaluate_locally=False,
         disable_geoip=None,
+        flag_keys_to_evaluate: Optional[list[str]] = None,
     ) -> FlagsAndPayloads:
         """
         Get all feature flags and their payloads for a user.
@@ -1737,6 +1794,8 @@ class Client(object):
             group_properties: A dictionary of group properties.
             only_evaluate_locally: Whether to only evaluate locally.
             disable_geoip: Whether to disable GeoIP for this request.
+            flag_keys_to_evaluate: A list of specific flag keys to evaluate. If provided,
+                only these flags will be evaluated, improving performance.
 
         Examples:
             ```python
@@ -1760,6 +1819,7 @@ class Client(object):
             groups=groups,
             person_properties=person_properties,
             group_properties=group_properties,
+            flag_keys_to_evaluate=flag_keys_to_evaluate,
         )
 
         if fallback_to_decide and not only_evaluate_locally:
@@ -1770,6 +1830,7 @@ class Client(object):
                     person_properties=person_properties,
                     group_properties=group_properties,
                     disable_geoip=disable_geoip,
+                    flag_keys_to_evaluate=flag_keys_to_evaluate,
                 )
                 return to_flags_and_payloads(decide_response)
             except Exception as e:
@@ -1787,6 +1848,7 @@ class Client(object):
         person_properties=None,
         group_properties=None,
         warn_on_unknown_groups=False,
+        flag_keys_to_evaluate: Optional[list[str]] = None,
     ) -> tuple[FlagsAndPayloads, bool]:
         person_properties = person_properties or {}
         group_properties = group_properties or {}
@@ -1799,7 +1861,15 @@ class Client(object):
         fallback_to_decide = False
         # If loading in previous line failed
         if self.feature_flags:
-            for flag in self.feature_flags:
+            # Filter flags based on flag_keys_to_evaluate if provided
+            flags_to_process = self.feature_flags
+            if flag_keys_to_evaluate:
+                flag_keys_set = set(flag_keys_to_evaluate)
+                flags_to_process = [
+                    flag for flag in self.feature_flags if flag["key"] in flag_keys_set
+                ]
+
+            for flag in flags_to_process:
                 try:
                     flags[flag["key"]] = self._compute_flag_locally(
                         flag,
@@ -1815,7 +1885,7 @@ class Client(object):
                     if matched_payload is not None:
                         payloads[flag["key"]] = matched_payload
                 except InconclusiveMatchError:
-                    # No need to log this, since it's just telling us to fall back to `/decide`
+                    # No need to log this, since it's just telling us to fall back to `/flags`
                     fallback_to_decide = True
                 except Exception as e:
                     self.log.exception(
@@ -1939,7 +2009,7 @@ class Client(object):
             for group_name in groups:
                 all_group_properties[group_name] = {
                     "$group_key": groups[group_name],
-                    **(group_properties.get(group_name) or {}),
+                    **((group_properties or {}).get(group_name) or {}),
                 }
 
         return all_person_properties, all_group_properties

{posthoganalytics-6.5.0 → posthoganalytics-6.6.1}/posthoganalytics/feature_flags.py

@@ -55,8 +55,100 @@ def variant_lookup_table(feature_flag):
     return lookup_table
 
 
+def evaluate_flag_dependency(
+    property, flags_by_key, evaluation_cache, distinct_id, properties, cohort_properties
+):
+    """
+    Evaluate a flag dependency property according to the dependency chain algorithm.
+
+    Args:
+        property: Flag property with type="flag" and dependency_chain
+        flags_by_key: Dictionary of all flags by their key
+        evaluation_cache: Cache for storing evaluation results
+        distinct_id: The distinct ID being evaluated
+        properties: Person properties for evaluation
+        cohort_properties: Cohort properties for evaluation
+
+    Returns:
+        bool: True if all dependencies in the chain evaluate to True, False otherwise
+    """
+    if flags_by_key is None or evaluation_cache is None:
+        # Cannot evaluate flag dependencies without required context
+        raise InconclusiveMatchError(
+            f"Cannot evaluate flag dependency on '{property.get('key', 'unknown')}' without flags_by_key and evaluation_cache"
+        )
+
+    # Check if dependency_chain is present - it should always be provided for flag dependencies
+    if "dependency_chain" not in property:
+        # Missing dependency_chain indicates malformed server data
+        raise InconclusiveMatchError(
+            f"Flag dependency property for '{property.get('key', 'unknown')}' is missing required 'dependency_chain' field"
+        )
+
+    dependency_chain = property["dependency_chain"]
+
+    # Handle circular dependency (empty chain means circular)
+    if len(dependency_chain) == 0:
+        log.debug(f"Circular dependency detected for flag: {property.get('key')}")
+        raise InconclusiveMatchError(
+            f"Circular dependency detected for flag '{property.get('key', 'unknown')}'"
+        )
+
+    # Evaluate all dependencies in the chain order
+    for dep_flag_key in dependency_chain:
+        if dep_flag_key not in evaluation_cache:
+            # Need to evaluate this dependency first
+            dep_flag = flags_by_key.get(dep_flag_key)
+            if not dep_flag:
+                # Missing flag dependency - cannot evaluate locally
+                evaluation_cache[dep_flag_key] = None
+                raise InconclusiveMatchError(
+                    f"Cannot evaluate flag dependency '{dep_flag_key}' - flag not found in local flags"
+                )
+            else:
+                # Check if the flag is active (same check as in client._compute_flag_locally)
+                if not dep_flag.get("active"):
+                    evaluation_cache[dep_flag_key] = False
+                else:
+                    # Recursively evaluate the dependency
+                    try:
+                        dep_result = match_feature_flag_properties(
+                            dep_flag,
+                            distinct_id,
+                            properties,
+                            cohort_properties,
+                            flags_by_key,
+                            evaluation_cache,
+                        )
+                        evaluation_cache[dep_flag_key] = dep_result
+                    except InconclusiveMatchError as e:
+                        # If we can't evaluate a dependency, store None and propagate the error
+                        evaluation_cache[dep_flag_key] = None
+                        raise InconclusiveMatchError(
+                            f"Cannot evaluate flag dependency '{dep_flag_key}': {e}"
+                        ) from e
+
+        # Check the cached result
+        cached_result = evaluation_cache[dep_flag_key]
+        if cached_result is None:
+            # Previously inconclusive - raise error again
+            raise InconclusiveMatchError(
+                f"Flag dependency '{dep_flag_key}' was previously inconclusive"
+            )
+        elif not cached_result:
+            # Definitive False result - dependency failed
+            return False
+
+    return True
+
+
 def match_feature_flag_properties(
-    flag, distinct_id, properties, cohort_properties=None
+    flag,
+    distinct_id,
+    properties,
+    cohort_properties=None,
+    flags_by_key=None,
+    evaluation_cache=None,
 ) -> FlagValue:
     flag_conditions = (flag.get("filters") or {}).get("groups") or []
     is_inconclusive = False
@@ -79,7 +171,13 @@ def match_feature_flag_properties(
             # if any one condition resolves to True, we can shortcircuit and return
             # the matching variant
             if is_condition_match(
-                flag, distinct_id, condition, properties, cohort_properties
+                flag,
+                distinct_id,
+                condition,
+                properties,
+                cohort_properties,
+                flags_by_key,
+                evaluation_cache,
             ):
                 variant_override = condition.get("variant")
                 if variant_override and variant_override in valid_variant_keys:
@@ -101,22 +199,36 @@ def match_feature_flag_properties(
 
 
 def is_condition_match(
-    feature_flag, distinct_id, condition, properties, cohort_properties
+    feature_flag,
+    distinct_id,
+    condition,
+    properties,
+    cohort_properties,
+    flags_by_key=None,
+    evaluation_cache=None,
 ) -> bool:
     rollout_percentage = condition.get("rollout_percentage")
     if len(condition.get("properties") or []) > 0:
         for prop in condition.get("properties"):
             property_type = prop.get("type")
             if property_type == "cohort":
-                matches = match_cohort(prop, properties, cohort_properties)
+                matches = match_cohort(
+                    prop,
+                    properties,
+                    cohort_properties,
+                    flags_by_key,
+                    evaluation_cache,
+                    distinct_id,
+                )
             elif property_type == "flag":
-                log.warning(
-                    "Flag dependency filters are not supported in local evaluation. "
-                    "Skipping condition for flag '%s' with dependency on flag '%s'",
-                    feature_flag.get("key", "unknown"),
-                    prop.get("key", "unknown"),
+                matches = evaluate_flag_dependency(
+                    prop,
+                    flags_by_key,
+                    evaluation_cache,
+                    distinct_id,
+                    properties,
+                    cohort_properties,
                 )
-                continue
             else:
                 matches = match_property(prop, properties)
             if not matches:
@@ -264,7 +376,14 @@ def match_property(property, property_values) -> bool:
     raise InconclusiveMatchError(f"Unknown operator {operator}")
 
 
-def match_cohort(property, property_values, cohort_properties) -> bool:
+def match_cohort(
+    property,
+    property_values,
+    cohort_properties,
+    flags_by_key=None,
+    evaluation_cache=None,
+    distinct_id=None,
+) -> bool:
     # Cohort properties are in the form of property groups like this:
     # {
     #     "cohort_id": {
@@ -281,10 +400,24 @@ def match_cohort(property, property_values, cohort_properties) -> bool:
         )
 
     property_group = cohort_properties[cohort_id]
-    return match_property_group(property_group, property_values, cohort_properties)
+    return match_property_group(
+        property_group,
+        property_values,
+        cohort_properties,
+        flags_by_key,
+        evaluation_cache,
+        distinct_id,
+    )
 
 
-def match_property_group(property_group, property_values, cohort_properties) -> bool:
+def match_property_group(
+    property_group,
+    property_values,
+    cohort_properties,
+    flags_by_key=None,
+    evaluation_cache=None,
+    distinct_id=None,
+) -> bool:
     if not property_group:
         return True
 
@@ -301,7 +434,14 @@ def match_property_group(property_group, property_values, cohort_properties) ->
         # a nested property group
         for prop in properties:
             try:
-                matches = match_property_group(prop, property_values, cohort_properties)
+                matches = match_property_group(
+                    prop,
+                    property_values,
+                    cohort_properties,
+                    flags_by_key,
+                    evaluation_cache,
+                    distinct_id,
+                )
                 if property_group_type == "AND":
                     if not matches:
                         return False
@@ -324,14 +464,23 @@ def match_property_group(property_group, property_values, cohort_properties) ->
         for prop in properties:
             try:
                 if prop.get("type") == "cohort":
-                    matches = match_cohort(prop, property_values, cohort_properties)
+                    matches = match_cohort(
+                        prop,
+                        property_values,
+                        cohort_properties,
+                        flags_by_key,
+                        evaluation_cache,
+                        distinct_id,
+                    )
                 elif prop.get("type") == "flag":
-                    log.warning(
-                        "Flag dependency filters are not supported in local evaluation. "
-                        "Skipping condition with dependency on flag '%s'",
-                        prop.get("key", "unknown"),
+                    matches = evaluate_flag_dependency(
+                        prop,
+                        flags_by_key,
+                        evaluation_cache,
+                        distinct_id,
+                        property_values,
+                        cohort_properties,
                     )
-                    continue
                 else:
                     matches = match_property(prop, property_values)