update version and changelog (#84)

* implementation with test

* format

* v=3 and get_all_payloads

* format

* fix bug

* format

* address comments

* format

* add tests

* format

* add resiliency

* fix lookup

* remove check

* address comments

* example.py

* format

* format

CHANGELOG.md

@@ -1,3 +1,52 @@
+## 2.3.0 - 2023-01-31
+
+1. Add support for returning payloads of matched feature flags
+
+## 2.2.0 - 2022-11-14
+
+Changes:
+
+1. Add support for feature flag variant overrides with local evaluation
+
+## 2.1.2 - 2022-09-15
+
+Changes:
+
+1. Fixes issues with date comparison.
+## 2.1.1 - 2022-09-14
+
+Changes:
+
+1. Feature flags local evaluation now supports date property filters as well. Accepts both strings and datetime objects.
+
+## 2.1.0 - 2022-08-11
+
+Changes:
+
+1. Feature flag defaults have been removed
+2. Setup logging only when debug mode is enabled.
+## 2.0.1 - 2022-08-04
+
+- Make poll_interval configurable
+- Add `send_feature_flag_events` parameter to feature flag calls, which determine whether the `$feature_flag_called` event should be sent or not.
+- Add `only_evaluate_locally` parameter to feature flag calls, which determines whether the feature flag should only be evaluated locally or not.
+
+## 2.0.0 - 2022-08-02
+
+Breaking changes:
+
+1. The minimum version requirement for PostHog servers is now 1.38. If you're using PostHog Cloud, you satisfy this requirement automatically.
+2. Feature flag defaults apply only when there's an error fetching feature flag results. Earlier, if the default was set to `True`, even if a flag resolved to `False`, the default would override this. 
+**Note: These are removed in 2.0.2**
+3. Feature flag remote evaluation doesn't require a personal API key.
+
+New Changes:
+
+1. You can now evaluate feature flags locally (i.e. without sending a request to your PostHog servers) by setting a personal API key, and passing in groups and person properties to `is_feature_enabled` and `get_feature_flag` calls.
+2. Introduces a `get_all_flags` method that returns all feature flags. This is useful for when you want to seed your frontend with some initial flags, given a user ID.
+
+
+
 ## 1.4.9 - 2022-06-13
 - Support for sending feature flags with capture calls
 

README.md

@@ -39,7 +39,7 @@ Then navigate to `http://127.0.0.1:8080/sentry-debug/` and you should get an eve
 
 ### Releasing Versions
 
-Updated are released using GitHub Actions: after bumping `version.py` in `master`, go to [our release workflow's page](https://github.com/PostHog/posthog-python/actions/workflows/release.yaml) and dispatch it manually, using workflow from `master`.
+Updated are released using GitHub Actions: after bumping `version.py` in `master` and adding to `CHANGELOG.md`, go to [our release workflow's page](https://github.com/PostHog/posthog-python/actions/workflows/release.yaml) and dispatch it manually, using workflow from `master`.
 
 ## Questions?
 

example.py

@@ -5,25 +5,45 @@ import time
 
 import posthog
 
+posthog.debug = True
+
 # You can find this key on the /setup page in PostHog
-posthog.project_api_key = ""
-posthog.personal_api_key = ""
+posthog.project_api_key = "phc_gtWmTq3Pgl06u4sZY3TRcoQfp42yfuXHKoe8ZVSR6Kh"
+posthog.personal_api_key = "phx_fiRCOQkTA3o2ePSdLrFDAILLHjMu2Mv52vUi8MNruIm"
 
 # Where you host PostHog, with no trailing /.
 # You can remove this line if you're using posthog.com
 posthog.host = "http://localhost:8000"
+posthog.poll_interval = 10
+
+print(
+    posthog.feature_enabled(
+        "person-on-events-enabled",
+        "12345",
+        groups={"organization": str("0182ee91-8ef7-0000-4cb9-fedc5f00926a")},
+        group_properties={
+            "organization": {
+                "id": "0182ee91-8ef7-0000-4cb9-fedc5f00926a",
+                "created_at": "2022-06-30 11:44:52.984121+00:00",
+            }
+        },
+        only_evaluate_locally=True,
+    )
+)
+
 
 # Capture an event
 posthog.capture("distinct_id", "event", {"property1": "value", "property2": "value"}, send_feature_flags=True)
 
 print(posthog.feature_enabled("beta-feature", "distinct_id"))
-print(posthog.feature_enabled("beta-feature", "distinct_id", groups={"company": "id:5"}))
-
-print("sleeping")
-time.sleep(5)
+print(posthog.feature_enabled("beta-feature-groups", "distinct_id", groups={"company": "id:5"}))
 
 print(posthog.feature_enabled("beta-feature", "distinct_id"))
 
+# get payload
+print(posthog.get_feature_flag_payload("beta-feature", "distinct_id"))
+print(posthog.get_all_flags_and_payloads("distinct_id"))
+exit()
 # # Alias a previous distinct id with a new one
 
 posthog.alias("distinct_id", "new_distinct_id")
@@ -42,7 +62,6 @@ posthog.group_identify("company", "id:5", {"employees": 11})
 # properties set only once to the person
 posthog.set_once("new_distinct_id", {"self_serve_signup": True})
 
-time.sleep(3)
 
 posthog.set_once(
     "new_distinct_id", {"self_serve_signup": False}
@@ -51,4 +70,32 @@ posthog.set_once(
 posthog.set("new_distinct_id", {"current_browser": "Chrome"})
 posthog.set("new_distinct_id", {"current_browser": "Firefox"})
 
-# posthog.shutdown()
+
+# #############################################################################
+# Make sure you have a personal API key for the examples below
+
+# Local Evaluation
+
+# If flag has City=Sydney, this call doesn't go to `/decide`
+print(posthog.feature_enabled("test-flag", "distinct_id_random_22", person_properties={"$geoip_city_name": "Sydney"}))
+
+print(
+    posthog.feature_enabled(
+        "test-flag",
+        "distinct_id_random_22",
+        person_properties={"$geoip_city_name": "Sydney"},
+        only_evaluate_locally=True,
+    )
+)
+
+
+print(posthog.get_all_flags("distinct_id_random_22"))
+print(posthog.get_all_flags("distinct_id_random_22", only_evaluate_locally=True))
+print(
+    posthog.get_all_flags(
+        "distinct_id_random_22", person_properties={"$geoip_city_name": "Sydney"}, only_evaluate_locally=True
+    )
+)
+
+
+posthog.shutdown()

posthog/__init__.py

@@ -15,6 +15,7 @@ sync_mode = False  # type: bool
 disabled = False  # type: bool
 personal_api_key = None  # type: str
 project_api_key = None  # type: str
+poll_interval = 30  # type: int
 
 default_client = None
 
@@ -234,8 +235,11 @@ def alias(
 def feature_enabled(
     key,  # type: str,
     distinct_id,  # type: str,
-    default=False,  # type: bool
     groups={},  # type: dict
+    person_properties={},  # type: dict
+    group_properties={},  # type: dict
+    only_evaluate_locally=False,  # type: bool
+    send_feature_flag_events=True,  # type: bool
 ):
     # type: (...) -> bool
     """
@@ -251,7 +255,125 @@ def feature_enabled(
 
     You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.
     """
-    return _proxy("feature_enabled", key=key, distinct_id=distinct_id, default=default, groups=groups)
+    return _proxy(
+        "feature_enabled",
+        key=key,
+        distinct_id=distinct_id,
+        groups=groups,
+        person_properties=person_properties,
+        group_properties=group_properties,
+        only_evaluate_locally=only_evaluate_locally,
+        send_feature_flag_events=send_feature_flag_events,
+    )
+
+
+def get_feature_flag(
+    key,  # type: str,
+    distinct_id,  # type: str,
+    groups={},  # type: dict
+    person_properties={},  # type: dict
+    group_properties={},  # type: dict
+    only_evaluate_locally=False,  # type: bool
+    send_feature_flag_events=True,  # type: bool
+):
+    """
+    Get feature flag variant for users. Used with experiments.
+    Example:
+    ```python
+    if posthog.get_feature_flag('beta-feature', 'distinct_id') == 'test-variant':
+        # do test variant code
+    if posthog.get_feature_flag('beta-feature', 'distinct_id') == 'control':
+        # do control code
+    ```
+
+    `groups` are a mapping from group type to group key. So, if you have a group type of "organization" and a group key of "5",
+    you would pass groups={"organization": "5"}.
+
+    `group_properties` take the format: { group_type_name: { group_properties } }
+
+    So, for example, if you have the group type "organization" and the group key "5", with the properties name, and employee count,
+    you'll send these as:
+
+    ```python
+        group_properties={"organization": {"name": "PostHog", "employees": 11}}
+    ```
+    """
+    return _proxy(
+        "get_feature_flag",
+        key=key,
+        distinct_id=distinct_id,
+        groups=groups,
+        person_properties=person_properties,
+        group_properties=group_properties,
+        only_evaluate_locally=only_evaluate_locally,
+        send_feature_flag_events=send_feature_flag_events,
+    )
+
+
+def get_all_flags(
+    distinct_id,  # type: str,
+    groups={},  # type: dict
+    person_properties={},  # type: dict
+    group_properties={},  # type: dict
+    only_evaluate_locally=False,  # type: bool
+):
+    """
+    Get all flags for a given user.
+    Example:
+    ```python
+    flags = posthog.get_all_flags('distinct_id')
+    ```
+
+    flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.
+    """
+    return _proxy(
+        "get_all_flags",
+        distinct_id=distinct_id,
+        groups=groups,
+        person_properties=person_properties,
+        group_properties=group_properties,
+        only_evaluate_locally=only_evaluate_locally,
+    )
+
+
+def get_feature_flag_payload(
+    key,
+    distinct_id,
+    match_value=None,
+    groups={},
+    person_properties={},
+    group_properties={},
+    only_evaluate_locally=False,
+    send_feature_flag_events=True,
+):
+    return _proxy(
+        "get_feature_flag_payload",
+        key=key,
+        distinct_id=distinct_id,
+        match_value=match_value,
+        groups=groups,
+        person_properties=person_properties,
+        group_properties=group_properties,
+        only_evaluate_locally=only_evaluate_locally,
+        send_feature_flag_events=send_feature_flag_events,
+    )
+
+
+def get_all_flags_and_payloads(
+    distinct_id,
+    groups={},
+    person_properties={},
+    group_properties={},
+    only_evaluate_locally=False,
+):
+    return _proxy(
+        "get_all_flags_and_payloads",
+        distinct_id=distinct_id,
+        groups=groups,
+        person_properties=person_properties,
+        group_properties=group_properties,
+        only_evaluate_locally=only_evaluate_locally,
+    )
 
 
 def page(*args, **kwargs):
@@ -295,6 +417,7 @@ def _proxy(method, *args, **kwargs):
             sync_mode=sync_mode,
             personal_api_key=personal_api_key,
             project_api_key=project_api_key,
+            poll_interval=poll_interval,
         )
 
     fn = getattr(default_client, method)

posthog/client.py

@@ -1,17 +1,17 @@
 import atexit
-import hashlib
 import logging
 import numbers
 from datetime import datetime, timedelta
-from uuid import UUID, uuid4
+from uuid import UUID
 
 from dateutil.tz import tzutc
 from six import string_types
 
 from posthog.consumer import Consumer
+from posthog.feature_flags import InconclusiveMatchError, match_feature_flag_properties
 from posthog.poller import Poller
 from posthog.request import APIError, batch_post, decide, get
-from posthog.utils import clean, guess_timezone
+from posthog.utils import SizeLimitedDict, clean, guess_timezone
 from posthog.version import VERSION
 
 try:
@@ -21,7 +21,7 @@ except ImportError:
 
 
 ID_TYPES = (numbers.Number, string_types, UUID)
-__LONG_SCALE__ = float(0xFFFFFFFFFFFFFFF)
+MAX_DICT_SIZE = 50_000
 
 
 class Client(object):
@@ -64,14 +64,21 @@ class Client(object):
         self.gzip = gzip
         self.timeout = timeout
         self.feature_flags = None
+        self.feature_flags_by_key = None
+        self.group_type_mapping = None
         self.poll_interval = poll_interval
         self.poller = None
+        self.distinct_ids_feature_flags_reported = SizeLimitedDict(MAX_DICT_SIZE, set)
 
         # personal_api_key: This should be a generated Personal API Key, private
         self.personal_api_key = personal_api_key
-
         if debug:
+            # Ensures that debug level messages are logged when debug mode is on.
+            # Otherwise, defaults to WARNING level. See https://docs.python.org/3/howto/logging.html#what-happens-if-no-configuration-is-provided
+            logging.basicConfig()
             self.log.setLevel(logging.DEBUG)
+        else:
+            self.log.setLevel(logging.WARNING)
 
         if sync_mode:
             self.consumers = None
@@ -120,8 +127,15 @@ class Client(object):
 
         return self._enqueue(msg)
 
-    def get_feature_variants(self, distinct_id, groups=None):
-        assert self.personal_api_key, "You have to specify a personal_api_key to use feature flags."
+    def get_feature_variants(self, distinct_id, groups=None, person_properties=None, group_properties=None):
+        resp_data = self.get_decide(distinct_id, groups, person_properties, group_properties)
+        return resp_data["featureFlags"]
+
+    def get_feature_payloads(self, distinct_id, groups=None, person_properties=None, group_properties=None):
+        resp_data = self.get_decide(distinct_id, groups, person_properties, group_properties)
+        return resp_data["featureFlagPayloads"]
+
+    def get_decide(self, distinct_id, groups=None, person_properties=None, group_properties=None):
         require("distinct_id", distinct_id, ID_TYPES)
 
         if groups:
@@ -131,11 +145,12 @@ class Client(object):
 
         request_data = {
             "distinct_id": distinct_id,
-            "personal_api_key": self.personal_api_key,
             "groups": groups,
+            "person_properties": person_properties,
+            "group_properties": group_properties,
         }
         resp_data = decide(self.api_key, self.host, timeout=10, **request_data)
-        return resp_data["featureFlags"]
+        return resp_data
 
     def capture(
         self,
@@ -352,8 +367,20 @@ class Client(object):
 
     def _load_feature_flags(self):
         try:
-            flags = get(self.personal_api_key, f"/api/feature_flag/?token={self.api_key}", self.host)["results"]
-            self.feature_flags = [flag for flag in flags if flag["active"]]
+
+            response = get(
+                self.personal_api_key,
+                f"/api/feature_flag/local_evaluation/?token={self.api_key}",
+                self.host,
+                timeout=10,
+            )
+
+            self.feature_flags = response["flags"] or []
+            self.feature_flags_by_key = {
+                flag["key"]: flag for flag in self.feature_flags if flag.get("key") is not None
+            }
+            self.group_type_mapping = response["group_type_mapping"] or {}
+
         except APIError as e:
             if e.status == 401:
                 raise APIError(
@@ -363,7 +390,7 @@ class Client(object):
                     "More information: https://posthog.com/docs/api/overview",
                 )
             else:
-                raise APIError(status=e.status, message=e.message)
+                self.log.error(f"[FEATURE FLAGS] Error loading feature flags: {e}")
         except Exception as e:
             self.log.warning(
                 "[FEATURE FLAGS] Fetching feature flags failed with following error. We will retry in %s seconds."
@@ -384,7 +411,75 @@ class Client(object):
             self.poller = Poller(interval=timedelta(seconds=self.poll_interval), execute=self._load_feature_flags)
             self.poller.start()
 
-    def feature_enabled(self, key, distinct_id, default=False, *, groups={}):
+    def _compute_flag_locally(self, feature_flag, distinct_id, *, groups={}, person_properties={}, group_properties={}):
+
+        if feature_flag.get("ensure_experience_continuity", False):
+            raise InconclusiveMatchError("Flag has experience continuity enabled")
+
+        if not feature_flag.get("active"):
+            return False
+
+        flag_filters = feature_flag.get("filters") or {}
+        aggregation_group_type_index = flag_filters.get("aggregation_group_type_index")
+        if aggregation_group_type_index is not None:
+            group_name = self.group_type_mapping.get(str(aggregation_group_type_index))
+
+            if not group_name:
+                self.log.warning(
+                    f"[FEATURE FLAGS] Unknown group type index {aggregation_group_type_index} for feature flag {feature_flag['key']}"
+                )
+                # failover to `/decide/`
+                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
+                self.log.warning(
+                    f"[FEATURE FLAGS] Can't compute group feature flag: {feature_flag['key']} without group names passed in"
+                )
+                return False
+
+            focused_group_properties = group_properties[group_name]
+            return match_feature_flag_properties(feature_flag, groups[group_name], focused_group_properties)
+        else:
+            return match_feature_flag_properties(feature_flag, distinct_id, person_properties)
+
+    def feature_enabled(
+        self,
+        key,
+        distinct_id,
+        *,
+        groups={},
+        person_properties={},
+        group_properties={},
+        only_evaluate_locally=False,
+        send_feature_flag_events=True,
+    ):
+        response = self.get_feature_flag(
+            key,
+            distinct_id,
+            groups=groups,
+            person_properties=person_properties,
+            group_properties=group_properties,
+            only_evaluate_locally=only_evaluate_locally,
+            send_feature_flag_events=send_feature_flag_events,
+        )
+
+        if response is None:
+            return None
+        return bool(response)
+
+    def get_feature_flag(
+        self,
+        key,
+        distinct_id,
+        *,
+        groups={},
+        person_properties={},
+        group_properties={},
+        only_evaluate_locally=False,
+        send_feature_flag_events=True,
+    ):
         require("key", key, string_types)
         require("distinct_id", distinct_id, ID_TYPES)
         require("groups", groups, dict)
@@ -397,34 +492,164 @@ class Client(object):
         if self.feature_flags:
             for flag in self.feature_flags:
                 if flag["key"] == key:
-                    feature_flag = flag
-                    if feature_flag.get("is_simple_flag"):
-                        rollout_percentage = (
-                            feature_flag.get("rollout_percentage")
-                            if feature_flag.get("rollout_percentage") is not None
-                            else 100
+                    try:
+                        response = self._compute_flag_locally(
+                            flag,
+                            distinct_id,
+                            groups=groups,
+                            person_properties=person_properties,
+                            group_properties=group_properties,
                         )
-                        response = _hash(key, distinct_id) <= (rollout_percentage / 100)
-        if response == None:
+                        self.log.debug(f"Successfully computed flag locally: {key} -> {response}")
+                    except InconclusiveMatchError as e:
+                        self.log.debug(f"Failed to compute flag {key} locally: {e}")
+                        continue
+                    except Exception as e:
+                        self.log.exception(f"[FEATURE FLAGS] Error while computing variant locally: {e}")
+                        continue
+
+        flag_was_locally_evaluated = response is not None
+        if not flag_was_locally_evaluated and not only_evaluate_locally:
             try:
-                feature_flags = self.get_feature_variants(distinct_id, groups=groups)
+                feature_flags = self.get_feature_variants(
+                    distinct_id, groups=groups, person_properties=person_properties, group_properties=group_properties
+                )
+                response = feature_flags.get(key)
+                if response is None:
+                    response = False
+                self.log.debug(f"Successfully computed flag remotely: #{key} -> #{response}")
             except Exception as e:
-                self.log.exception(f"[FEATURE FLAGS] Unable to get feature variants: {e}")
-                response = default
-            else:
-                response = feature_flags.get(key, default)
-        self.capture(distinct_id, "$feature_flag_called", {"$feature_flag": key, "$feature_flag_response": response})
+                self.log.exception(f"[FEATURE FLAGS] Unable to get flag remotely: {e}")
+
+        feature_flag_reported_key = f"{key}_{str(response)}"
+        if (
+            feature_flag_reported_key not in self.distinct_ids_feature_flags_reported[distinct_id]
+            and send_feature_flag_events
+        ):
+            self.capture(
+                distinct_id,
+                "$feature_flag_called",
+                {
+                    "$feature_flag": key,
+                    "$feature_flag_response": response,
+                    "locally_evaluated": flag_was_locally_evaluated,
+                },
+                groups=groups,
+            )
+            self.distinct_ids_feature_flags_reported[distinct_id].add(feature_flag_reported_key)
         return response
 
+    def get_feature_flag_payload(
+        self,
+        key,
+        distinct_id,
+        *,
+        match_value=None,
+        groups={},
+        person_properties={},
+        group_properties={},
+        only_evaluate_locally=False,
+        send_feature_flag_events=True,
+    ):
+        if match_value is None:
+            match_value = self.get_feature_flag(
+                key,
+                distinct_id,
+                groups=groups,
+                person_properties=person_properties,
+                group_properties=group_properties,
+                send_feature_flag_events=send_feature_flag_events,
+                only_evaluate_locally=True,
+            )
 
-# This function takes a distinct_id and a feature flag key and returns a float between 0 and 1.
-# Given the same distinct_id and key, it'll always return the same float. These floats are
-# uniformly distributed between 0 and 1, so if we want to show this feature to 20% of traffic
-# we can do _hash(key, distinct_id) < 0.2
-def _hash(key, distinct_id):
-    hash_key = "%s.%s" % (key, distinct_id)
-    hash_val = int(hashlib.sha1(hash_key.encode("utf-8")).hexdigest()[:15], 16)
-    return hash_val / __LONG_SCALE__
+        response = None
+
+        if match_value is not None:
+            response = self._compute_payload_locally(key, match_value)
+
+        if response is None and not only_evaluate_locally:
+            decide_payloads = self.get_feature_payloads(distinct_id, groups, person_properties, group_properties)
+            response = decide_payloads.get(str(key).lower(), None)
+
+        return response
+
+    def _compute_payload_locally(self, key, match_value):
+        payload = None
+
+        if self.feature_flags_by_key is None:
+            return payload
+
+        flag_definition = self.feature_flags_by_key.get(key) or {}
+        flag_filters = flag_definition.get("filters") or {}
+        flag_payloads = flag_filters.get("payloads") or {}
+        payload = flag_payloads.get(str(match_value).lower(), None)
+        return payload
+
+    def get_all_flags(
+        self, distinct_id, *, groups={}, person_properties={}, group_properties={}, only_evaluate_locally=False
+    ):
+        flags = self.get_all_flags_and_payloads(
+            distinct_id,
+            groups=groups,
+            person_properties=person_properties,
+            group_properties=group_properties,
+            only_evaluate_locally=only_evaluate_locally,
+        )
+        return flags["featureFlags"]
+
+    def get_all_flags_and_payloads(
+        self, distinct_id, *, groups={}, person_properties={}, group_properties={}, only_evaluate_locally=False
+    ):
+        flags, payloads, fallback_to_decide = self._get_all_flags_and_payloads_locally(
+            distinct_id, groups=groups, person_properties=person_properties, group_properties=group_properties
+        )
+        response = {"featureFlags": flags, "featureFlagPayloads": payloads}
+
+        if fallback_to_decide and not only_evaluate_locally:
+            try:
+                flags_and_payloads = self.get_decide(
+                    distinct_id, groups=groups, person_properties=person_properties, group_properties=group_properties
+                )
+                response = flags_and_payloads
+            except Exception as e:
+                self.log.exception(f"[FEATURE FLAGS] Unable to get feature flags and payloads: {e}")
+
+        return response
+
+    def _get_all_flags_and_payloads_locally(self, distinct_id, *, groups={}, person_properties={}, group_properties={}):
+        require("distinct_id", distinct_id, ID_TYPES)
+        require("groups", groups, dict)
+
+        if self.feature_flags == None and self.personal_api_key:
+            self.load_feature_flags()
+
+        flags = {}
+        payloads = {}
+        fallback_to_decide = False
+        # If loading in previous line failed
+        if self.feature_flags:
+            for flag in self.feature_flags:
+                try:
+                    flags[flag["key"]] = self._compute_flag_locally(
+                        flag,
+                        distinct_id,
+                        groups=groups,
+                        person_properties=person_properties,
+                        group_properties=group_properties,
+                    )
+                    matched_payload = self._compute_payload_locally(flag["key"], flags[flag["key"]])
+                    if matched_payload:
+                        payloads[flag["key"]] = matched_payload
+                except InconclusiveMatchError as e:
+                    # No need to log this, since it's just telling us to fall back to `/decide`
+                    fallback_to_decide = True
+                except Exception as e:
+                    self.log.exception(f"[FEATURE FLAGS] Error while computing variant and payload: {e}")
+                    fallback_to_decide = True
+        else:
+            fallback_to_decide = True
+
+        return flags, payloads, fallback_to_decide
 
 
 def require(name, field, data_type):

posthog/feature_flags.py

@@ -0,0 +1,177 @@
+import datetime
+import hashlib
+import re
+
+from dateutil import parser
+
+from posthog.utils import convert_to_datetime_aware, is_valid_regex
+
+__LONG_SCALE__ = float(0xFFFFFFFFFFFFFFF)
+
+
+class InconclusiveMatchError(Exception):
+    pass
+
+
+# This function takes a distinct_id and a feature flag key and returns a float between 0 and 1.
+# Given the same distinct_id and key, it'll always return the same float. These floats are
+# uniformly distributed between 0 and 1, so if we want to show this feature to 20% of traffic
+# we can do _hash(key, distinct_id) < 0.2
+def _hash(key, distinct_id, salt=""):
+    hash_key = f"{key}.{distinct_id}{salt}"
+    hash_val = int(hashlib.sha1(hash_key.encode("utf-8")).hexdigest()[:15], 16)
+    return hash_val / __LONG_SCALE__
+
+
+def get_matching_variant(flag, distinct_id):
+    hash_value = _hash(flag["key"], distinct_id, salt="variant")
+    for variant in variant_lookup_table(flag):
+        if hash_value >= variant["value_min"] and hash_value < variant["value_max"]:
+            return variant["key"]
+    return None
+
+
+def variant_lookup_table(feature_flag):
+    lookup_table = []
+    value_min = 0
+    multivariates = ((feature_flag.get("filters") or {}).get("multivariate") or {}).get("variants") or []
+    for variant in multivariates:
+        value_max = value_min + variant["rollout_percentage"] / 100
+        lookup_table.append({"value_min": value_min, "value_max": value_max, "key": variant["key"]})
+        value_min = value_max
+    return lookup_table
+
+
+def match_feature_flag_properties(flag, distinct_id, properties):
+    flag_conditions = (flag.get("filters") or {}).get("groups") or []
+    is_inconclusive = False
+
+    # Stable sort conditions with variant overrides to the top. This ensures that if overrides are present, they are
+    # evaluated first, and the variant override is applied to the first matching condition.
+    sorted_flag_conditions = sorted(
+        flag_conditions,
+        key=lambda condition: 0 if condition.get("variant") else 1,
+    )
+
+    for condition in sorted_flag_conditions:
+        try:
+            # if any one condition resolves to True, we can shortcircuit and return
+            # the matching variant
+            if is_condition_match(flag, distinct_id, condition, properties):
+                variant_override = condition.get("variant")
+                # Some filters can be explicitly set to null, which require accessing variants like so
+                flag_variants = ((flag.get("filters") or {}).get("multivariate") or {}).get("variants") or []
+                if variant_override and variant_override in [variant["key"] for variant in flag_variants]:
+                    variant = variant_override
+                else:
+                    variant = get_matching_variant(flag, distinct_id)
+                return variant or True
+        except InconclusiveMatchError:
+            is_inconclusive = True
+
+    if is_inconclusive:
+        raise InconclusiveMatchError("Can't determine if feature flag is enabled or not with given properties")
+
+    # We can only return False when either all conditions are False, or
+    # no condition was inconclusive.
+    return False
+
+
+def is_condition_match(feature_flag, distinct_id, condition, properties):
+    rollout_percentage = condition.get("rollout_percentage")
+    if len(condition.get("properties") or []) > 0:
+        if not all(match_property(prop, properties) for prop in condition.get("properties")):
+            return False
+        elif rollout_percentage is None:
+            return True
+
+    if rollout_percentage is not None and _hash(feature_flag["key"], distinct_id) > (rollout_percentage / 100):
+        return False
+
+    return True
+
+
+def match_property(property, property_values) -> bool:
+    # only looks for matches where key exists in override_property_values
+    # doesn't support operator is_not_set
+    key = property.get("key")
+    operator = property.get("operator") or "exact"
+    value = property.get("value")
+
+    if key not in property_values:
+        raise InconclusiveMatchError("can't match properties without a given property value")
+
+    if operator == "is_not_set":
+        raise InconclusiveMatchError("can't match properties with operator is_not_set")
+
+    override_value = property_values[key]
+
+    if operator == "exact":
+        if isinstance(value, list):
+            return override_value in value
+        return value == override_value
+
+    if operator == "is_not":
+        if isinstance(value, list):
+            return override_value not in value
+        return value != override_value
+
+    if operator == "is_set":
+        return key in property_values
+
+    if operator == "icontains":
+        return str(value).lower() in str(override_value).lower()
+
+    if operator == "not_icontains":
+        return str(value).lower() not in str(override_value).lower()
+
+    if operator == "regex":
+        return is_valid_regex(str(value)) and re.compile(str(value)).search(str(override_value)) is not None
+
+    if operator == "not_regex":
+        return is_valid_regex(str(value)) and re.compile(str(value)).search(str(override_value)) is None
+
+    if operator == "gt":
+        return type(override_value) == type(value) and override_value > value
+
+    if operator == "gte":
+        return type(override_value) == type(value) and override_value >= value
+
+    if operator == "lt":
+        return type(override_value) == type(value) and override_value < value
+
+    if operator == "lte":
+        return type(override_value) == type(value) and override_value <= value
+
+    if operator in ["is_date_before", "is_date_after"]:
+        try:
+            parsed_date = parser.parse(value)
+            parsed_date = convert_to_datetime_aware(parsed_date)
+        except Exception:
+            raise InconclusiveMatchError("The date set on the flag is not a valid format")
+
+        if isinstance(override_value, datetime.datetime):
+            override_date = convert_to_datetime_aware(override_value)
+            if operator == "is_date_before":
+                return override_date < parsed_date
+            else:
+                return override_date > parsed_date
+        elif isinstance(override_value, datetime.date):
+            if operator == "is_date_before":
+                return override_value < parsed_date.date()
+            else:
+                return override_value > parsed_date.date()
+        elif isinstance(override_value, str):
+            try:
+                override_date = parser.parse(override_value)
+                override_date = convert_to_datetime_aware(override_date)
+                if operator == "is_date_before":
+                    return override_date < parsed_date
+                else:
+                    return override_date > parsed_date
+            except Exception:
+                raise InconclusiveMatchError("The date provided is not a valid format")
+        else:
+            raise InconclusiveMatchError("The date provided must be a string or date object")
+
+    return False

posthog/request.py

@@ -50,11 +50,6 @@ def _process_response(
     res: requests.Response, success_message: str, *, return_json: bool = True
 ) -> Union[requests.Response, Any]:
     log = logging.getLogger("posthog")
-    if not res:
-        raise APIError(
-            "N/A",
-            "Error when fetching PostHog API, please make sure you are using your public project token/key and not a private API key.",
-        )
     if res.status_code == 200:
         log.debug(success_message)
         return res.json() if return_json else res
@@ -62,13 +57,13 @@ def _process_response(
         payload = res.json()
         log.debug("received response: %s", payload)
         raise APIError(res.status_code, payload["detail"])
-    except ValueError:
+    except (KeyError, ValueError):
         raise APIError(res.status_code, res.text)
 
 
 def decide(api_key: str, host: Optional[str] = None, gzip: bool = False, timeout: int = 15, **kwargs) -> Any:
     """Post the `kwargs to the decide API endpoint"""
-    res = post(api_key, host, "/decide/?v=2", gzip, timeout, **kwargs)
+    res = post(api_key, host, "/decide/?v=3", gzip, timeout, **kwargs)
     return _process_response(res, success_message="Feature flags decided successfully")
 
 

posthog/test/test_client.py

@@ -6,15 +6,26 @@ from uuid import uuid4
 
 import mock
 import six
-from freezegun import freeze_time
 
 from posthog.client import Client
-from posthog.request import APIError
-from posthog.test.test_utils import TEST_API_KEY
+from posthog.test.test_utils import FAKE_TEST_API_KEY
 from posthog.version import VERSION
 
 
 class TestClient(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        # This ensures no real HTTP POST requests are made
+        cls.client_post_patcher = mock.patch("posthog.client.batch_post")
+        cls.consumer_post_patcher = mock.patch("posthog.consumer.batch_post")
+        cls.client_post_patcher.start()
+        cls.consumer_post_patcher.start()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.client_post_patcher.stop()
+        cls.consumer_post_patcher.stop()
+
     def set_fail(self, e, batch):
         """Mark the failure handler"""
         print("FAIL", e, batch)
@@ -22,7 +33,7 @@ class TestClient(unittest.TestCase):
 
     def setUp(self):
         self.failed = False
-        self.client = Client(TEST_API_KEY, on_error=self.set_fail)
+        self.client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail)
 
     def test_requires_api_key(self):
         self.assertRaises(AssertionError, Client)
@@ -61,7 +72,7 @@ class TestClient(unittest.TestCase):
 
     def test_basic_capture_with_project_api_key(self):
 
-        client = Client(project_api_key=TEST_API_KEY, on_error=self.set_fail)
+        client = Client(project_api_key=FAKE_TEST_API_KEY, on_error=self.set_fail)
 
         success, msg = client.capture("distinct_id", "python test event")
         client.flush()
@@ -79,7 +90,7 @@ class TestClient(unittest.TestCase):
     def test_basic_capture_with_feature_flags(self, patch_decide):
         patch_decide.return_value = {"featureFlags": {"beta-feature": "random-variant"}}
 
-        client = Client(TEST_API_KEY, on_error=self.set_fail, personal_api_key=TEST_API_KEY)
+        client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, personal_api_key=FAKE_TEST_API_KEY)
         success, msg = client.capture("distinct_id", "python test event", send_feature_flags=True)
         client.flush()
         self.assertTrue(success)
@@ -100,7 +111,7 @@ class TestClient(unittest.TestCase):
     def test_basic_capture_with_feature_flags_switched_off_doesnt_send_them(self, patch_decide):
         patch_decide.return_value = {"featureFlags": {"beta-feature": "random-variant"}}
 
-        client = Client(TEST_API_KEY, on_error=self.set_fail, personal_api_key=TEST_API_KEY)
+        client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, personal_api_key=FAKE_TEST_API_KEY)
         success, msg = client.capture("distinct_id", "python test event", send_feature_flags=False)
         client.flush()
         self.assertTrue(success)
@@ -117,29 +128,6 @@ class TestClient(unittest.TestCase):
 
         self.assertEqual(patch_decide.call_count, 0)
 
-    @mock.patch("posthog.client.decide")
-    def test_basic_capture_with_feature_flags_without_api_key(self, patch_decide):
-        patch_decide.return_value = {"featureFlags": {"beta-feature": "random-variant"}}
-
-        client = Client(project_api_key=TEST_API_KEY, on_error=self.set_fail)
-        client.log = MagicMock()
-        success, msg = client.capture("distinct_id", "python test event", send_feature_flags=True)
-        client.flush()
-        self.assertTrue(success)
-        self.assertFalse(self.failed)
-
-        self.assertEqual(msg["event"], "python test event")
-        self.assertTrue(isinstance(msg["timestamp"], str))
-        self.assertIsNone(msg.get("uuid"))
-        self.assertEqual(msg["distinct_id"], "distinct_id")
-        self.assertEqual(msg["properties"]["$lib"], "posthog-python")
-        self.assertEqual(msg["properties"]["$lib_version"], VERSION)
-
-        self.assertEqual(client.log.exception.call_count, 1)
-        client.log.exception.assert_called_with(
-            "[FEATURE FLAGS] Unable to get feature variants: You have to specify a personal_api_key to use feature flags."
-        )
-
     def test_stringifies_distinct_id(self):
         # A large number that loses precision in node:
         # node -e "console.log(157963456373623802 + 1)" > 157963456373623800
@@ -387,7 +375,7 @@ class TestClient(unittest.TestCase):
             self.assertFalse(consumer.is_alive())
 
     def test_synchronous(self):
-        client = Client(TEST_API_KEY, sync_mode=True)
+        client = Client(FAKE_TEST_API_KEY, sync_mode=True)
 
         success, message = client.identify("distinct_id")
         self.assertFalse(client.consumers)
@@ -395,7 +383,7 @@ class TestClient(unittest.TestCase):
         self.assertTrue(success)
 
     def test_overflow(self):
-        client = Client(TEST_API_KEY, max_queue_size=1)
+        client = Client(FAKE_TEST_API_KEY, max_queue_size=1)
         # Ensure consumer thread is no longer uploading
         client.join()
 
@@ -418,14 +406,14 @@ class TestClient(unittest.TestCase):
         Client("bad_key", debug=True)
 
     def test_gzip(self):
-        client = Client(TEST_API_KEY, on_error=self.fail, gzip=True)
+        client = Client(FAKE_TEST_API_KEY, on_error=self.fail, gzip=True)
         for _ in range(10):
             client.identify("distinct_id", {"trait": "value"})
         client.flush()
         self.assertFalse(self.failed)
 
     def test_user_defined_flush_at(self):
-        client = Client(TEST_API_KEY, on_error=self.fail, flush_at=10, flush_interval=3)
+        client = Client(FAKE_TEST_API_KEY, on_error=self.fail, flush_at=10, flush_interval=3)
 
         def mock_post_fn(*args, **kwargs):
             self.assertEqual(len(kwargs["batch"]), 10)
@@ -439,139 +427,15 @@ class TestClient(unittest.TestCase):
             self.assertEqual(mock_post.call_count, 2)
 
     def test_user_defined_timeout(self):
-        client = Client(TEST_API_KEY, timeout=10)
+        client = Client(FAKE_TEST_API_KEY, timeout=10)
         for consumer in client.consumers:
             self.assertEqual(consumer.timeout, 10)
 
     def test_default_timeout_15(self):
-        client = Client(TEST_API_KEY)
+        client = Client(FAKE_TEST_API_KEY)
         for consumer in client.consumers:
             self.assertEqual(consumer.timeout, 15)
 
-    @mock.patch("posthog.client.Poller")
-    @mock.patch("posthog.client.get")
-    def test_load_feature_flags(self, patch_get, patch_poll):
-        patch_get.return_value = {
-            "results": [
-                {"id": 1, "name": "Beta Feature", "key": "beta-feature", "active": True},
-                {"id": 2, "name": "Alpha Feature", "key": "alpha-feature", "active": False},
-            ]
-        }
-        client = Client(TEST_API_KEY, personal_api_key="test")
-        with freeze_time("2020-01-01T12:01:00.0000Z"):
-            client.load_feature_flags()
-        self.assertEqual(len(client.feature_flags), 1)
-        self.assertEqual(client.feature_flags[0]["key"], "beta-feature")
-        self.assertEqual(client._last_feature_flag_poll.isoformat(), "2020-01-01T12:01:00+00:00")
-        self.assertEqual(patch_poll.call_count, 1)
-
-    def test_load_feature_flags_wrong_key(self):
-        client = Client(TEST_API_KEY, personal_api_key=TEST_API_KEY)
-        with freeze_time("2020-01-01T12:01:00.0000Z"):
-            self.assertRaises(APIError, client.load_feature_flags)
-
-    @mock.patch("posthog.client.decide")
-    @mock.patch("posthog.client.get")
-    def test_feature_enabled_simple(self, patch_get, patch_decide):
-        client = Client(TEST_API_KEY)
-        client.feature_flags = [
-            {"id": 1, "name": "Beta Feature", "key": "beta-feature", "is_simple_flag": True, "rollout_percentage": 100}
-        ]
-        self.assertTrue(client.feature_enabled("beta-feature", "distinct_id"))
-        self.assertEqual(patch_decide.call_count, 0)
-
-    @mock.patch("posthog.client.decide")
-    @mock.patch("posthog.client.get")
-    def test_feature_enabled_simple_is_false(self, patch_get, patch_decide):
-        client = Client(TEST_API_KEY)
-        client.feature_flags = [
-            {"id": 1, "name": "Beta Feature", "key": "beta-feature", "is_simple_flag": True, "rollout_percentage": 0}
-        ]
-        self.assertFalse(client.feature_enabled("beta-feature", "distinct_id"))
-        self.assertEqual(patch_decide.call_count, 0)
-
-    @mock.patch("posthog.client.decide")
-    @mock.patch("posthog.client.get")
-    def test_feature_enabled_simple_is_true_when_rollout_is_undefined(self, patch_get, patch_decide):
-        client = Client(TEST_API_KEY)
-        client.feature_flags = [
-            {"id": 1, "name": "Beta Feature", "key": "beta-feature", "is_simple_flag": True, "rollout_percentage": None}
-        ]
-        self.assertTrue(client.feature_enabled("beta-feature", "distinct_id"))
-        self.assertEqual(patch_decide.call_count, 0)
-
-    @mock.patch("posthog.client.get")
-    def test_feature_enabled_simple_with_project_api_key(self, patch_get):
-        client = Client(project_api_key=TEST_API_KEY, on_error=self.set_fail)
-        client.feature_flags = [
-            {"id": 1, "name": "Beta Feature", "key": "beta-feature", "is_simple_flag": True, "rollout_percentage": 100}
-        ]
-        self.assertTrue(client.feature_enabled("beta-feature", "distinct_id"))
-
-    @mock.patch("posthog.client.decide")
-    def test_feature_enabled_request(self, patch_decide):
-        patch_decide.return_value = {"featureFlags": {"beta-feature": True}}
-        client = Client(TEST_API_KEY, personal_api_key="test")
-        client.feature_flags = [
-            {"id": 1, "name": "Beta Feature", "key": "beta-feature", "is_simple_flag": False, "rollout_percentage": 100}
-        ]
-        self.assertTrue(client.feature_enabled("beta-feature", "distinct_id"))
-
-    @mock.patch("posthog.client.decide")
-    def test_feature_enabled_request_multi_variate(self, patch_decide):
-        patch_decide.return_value = {"featureFlags": {"beta-feature": "variant-1"}}
-        client = Client(TEST_API_KEY, personal_api_key="test")
-        client.feature_flags = [
-            {"id": 1, "name": "Beta Feature", "key": "beta-feature", "is_simple_flag": False, "rollout_percentage": 100}
-        ]
-        self.assertEqual(client.feature_enabled("beta-feature", "distinct_id"), "variant-1")
-
-    @mock.patch("posthog.client.get")
-    def test_feature_enabled_simple_without_rollout_percentage(self, patch_get):
-        client = Client(TEST_API_KEY)
-        client.feature_flags = [{"id": 1, "name": "Beta Feature", "key": "beta-feature", "is_simple_flag": True}]
-        self.assertTrue(client.feature_enabled("beta-feature", "distinct_id"))
-
-    @mock.patch("posthog.client.get")
-    def test_feature_enabled_simple_with_none_rollout_percentage(self, patch_get):
-        client = Client(TEST_API_KEY)
-        client.feature_flags = [
-            {"id": 1, "name": "Beta Feature", "key": "beta-feature", "is_simple_flag": True, "rollout_percantage": None}
-        ]
-        self.assertTrue(client.feature_enabled("beta-feature", "distinct_id"))
-
-    @mock.patch("posthog.client.Poller")
-    @mock.patch("posthog.client.decide")
-    def test_feature_enabled_doesnt_exist(self, patch_decide, patch_poll):
-        patch_decide.return_value = {"featureFlags": {}}
-        client = Client(TEST_API_KEY)
-        client.feature_flags = []
-
-        self.assertFalse(client.feature_enabled("doesnt-exist", "distinct_id"))
-        self.assertTrue(client.feature_enabled("doesnt-exist", "distinct_id", True))
-
-    @mock.patch("posthog.client.Poller")
-    @mock.patch("posthog.client.decide")
-    def test_personal_api_key_doesnt_exist(self, patch_decide, patch_poll):
-        client = Client(TEST_API_KEY, personal_api_key="test")
-        client.feature_flags = []
-
-        patch_decide.return_value = {"featureFlags": {"feature-flag": True}}
-
-        self.assertTrue(client.feature_enabled("feature-flag", "distinct_id"))
-
-    @mock.patch("posthog.client.Poller")
-    @mock.patch("posthog.client.get")
-    def test_load_feature_flags_error(self, patch_get, patch_poll):
-        def raise_effect():
-            raise Exception("http exception")
-
-        patch_get.return_value.raiseError.side_effect = raise_effect
-        client = Client(TEST_API_KEY, personal_api_key="test")
-        client.feature_flags = []
-
-        self.assertFalse(client.feature_enabled("doesnt-exist", "distinct_id"))
-
     @mock.patch("posthog.client.Poller")
     @mock.patch("posthog.client.get")
     def test_call_identify_fails(self, patch_get, patch_poll):
@@ -579,7 +443,7 @@ class TestClient(unittest.TestCase):
             raise Exception("http exception")
 
         patch_get.return_value.raiseError.side_effect = raise_effect
-        client = Client(TEST_API_KEY, personal_api_key="test")
+        client = Client(FAKE_TEST_API_KEY, personal_api_key="test")
         client.feature_flags = [{"key": "example", "is_simple_flag": False}]
 
         self.assertFalse(client.feature_enabled("example", "distinct_id"))

posthog/test/test_utils.py

@@ -9,6 +9,7 @@ from dateutil.tz import tzutc
 from posthog import utils
 
 TEST_API_KEY = "kOOlRy2QlMY9jHZQv0bKz0FZyazBUoY8Arj0lFVNjs4"
+FAKE_TEST_API_KEY = "random_key"
 
 
 class TestUtils(unittest.TestCase):
@@ -79,3 +80,22 @@ class TestUtils(unittest.TestCase):
     def test_remove_slash(self):
         self.assertEqual("http://posthog.io", utils.remove_trailing_slash("http://posthog.io/"))
         self.assertEqual("http://posthog.io", utils.remove_trailing_slash("http://posthog.io"))
+
+
+class TestSizeLimitedDict(unittest.TestCase):
+    def test_size_limited_dict(self):
+        size = 10
+        values = utils.SizeLimitedDict(size, lambda _: -1)
+
+        for i in range(100):
+            values[i] = i
+
+            self.assertEqual(values[i], i)
+            self.assertEqual(len(values), i % size + 1)
+
+            if i % size == 0:
+                # old numbers should've been removed
+                self.assertIsNone(values.get(i - 1))
+                self.assertIsNone(values.get(i - 3))
+                self.assertIsNone(values.get(i - 5))
+                self.assertIsNone(values.get(i - 9))

posthog/utils.py

@@ -1,6 +1,8 @@
 import logging
 import numbers
-from datetime import date, datetime
+import re
+from collections import defaultdict
+from datetime import date, datetime, timezone
 from decimal import Decimal
 from uuid import UUID
 
@@ -87,3 +89,29 @@ def _coerce_unicode(cmplx):
         log.warning("Error decoding: %s", item)
         return None
     return item
+
+
+def is_valid_regex(value) -> bool:
+    try:
+        re.compile(value)
+        return True
+    except re.error:
+        return False
+
+
+class SizeLimitedDict(defaultdict):
+    def __init__(self, max_size, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.max_size = max_size
+
+    def __setitem__(self, key, value):
+        if len(self) >= self.max_size:
+            self.clear()
+
+        super().__setitem__(key, value)
+
+
+def convert_to_datetime_aware(date_obj):
+    if date_obj.tzinfo is None:
+        date_obj = date_obj.replace(tzinfo=timezone.utc)
+    return date_obj

posthog/version.py

@@ -1,4 +1,4 @@
-VERSION = "1.4.9"
+VERSION = "2.3.0"
 
 if __name__ == "__main__":
     print(VERSION, end="")