openfeature-provider-posthog 0.1.1__py3-none-any.whl

openfeature/contrib/provider/posthog/__init__.py

@@ -0,0 +1,3 @@
+from openfeature.contrib.provider.posthog.provider import PostHogProvider
+
+__all__ = ["PostHogProvider"]

openfeature/contrib/provider/posthog/provider.py

@@ -0,0 +1,285 @@
+"""Official PostHog provider for the OpenFeature Python SDK.
+
+This wraps a configured :class:`posthog.Posthog` client and exposes flag
+evaluation through OpenFeature's :class:`~openfeature.provider.AbstractProvider`
+contract, using the modern, single-call ``Client.get_feature_flag_result`` API.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Mapping, Optional, Sequence, TypeVar, Union
+
+from openfeature.evaluation_context import EvaluationContext
+from openfeature.exception import (
+    FlagNotFoundError,
+    TargetingKeyMissingError,
+    TypeMismatchError,
+)
+from openfeature.flag_evaluation import FlagResolutionDetails, Reason
+from openfeature.provider import AbstractProvider
+from openfeature.provider.metadata import Metadata
+
+import posthog
+from posthog.types import FeatureFlagResult
+
+# Reserved evaluation-context attribute keys. Every other attribute in
+# ``evaluation_context.attributes`` is forwarded as a PostHog person property.
+GROUPS_KEY = "groups"
+GROUP_PROPERTIES_KEY = "group_properties"
+_RESERVED_KEYS = frozenset({GROUPS_KEY, GROUP_PROPERTIES_KEY})
+
+ObjectValue = Union[Sequence[Any], Mapping[str, Any]]
+
+_T = TypeVar("_T")
+_N = TypeVar("_N", int, float)
+
+_logger = logging.getLogger(__name__)
+
+
+class PostHogProvider(AbstractProvider):
+    """OpenFeature provider backed by a configured :class:`posthog.Posthog` client.
+
+    The caller owns the PostHog client lifecycle: construct and configure the
+    client yourself (project key, ``personal_api_key`` for local evaluation,
+    ``host``, ...), then hand it to this provider.
+
+    Evaluation-context mapping:
+        * ``targeting_key``               -> PostHog ``distinct_id``
+        * reserved attr ``groups``        -> PostHog ``groups``
+        * reserved attr ``group_properties`` -> PostHog ``group_properties``
+        * every other attribute           -> PostHog ``person_properties``
+
+    Flag-type mapping (all via ``get_feature_flag_result``):
+        * boolean -> ``enabled``
+        * string  -> the multivariate ``variant`` key
+        * int/float -> the ``variant`` parsed to a number
+        * object  -> the flag's JSON ``payload``
+
+    Args:
+        client: A configured :class:`posthog.Posthog` instance.
+        default_distinct_id: Distinct ID to use when the evaluation context has
+            no ``targeting_key``. If ``None`` (default), a missing targeting key
+            raises :class:`~openfeature.exception.TargetingKeyMissingError`,
+            which is OpenFeature-idiomatic. Set a value (e.g. ``"anonymous"``)
+            to opt into anonymous evaluation.
+        send_feature_flag_events: Forwarded to ``get_feature_flag_result`` to
+            control ``$feature_flag_called`` capture. Defaults to ``True`` so
+            PostHog flag analytics (and experiments) keep working.
+    """
+
+    def __init__(
+        self,
+        client: posthog.Posthog,
+        *,
+        default_distinct_id: Optional[str] = None,
+        send_feature_flag_events: bool = True,
+    ) -> None:
+        super().__init__()
+        self._client = client
+        self._default_distinct_id = default_distinct_id
+        self._send_feature_flag_events = send_feature_flag_events
+
+    # -- metadata / lifecycle -------------------------------------------------
+
+    def get_metadata(self) -> Metadata:
+        return Metadata(name="PostHogProvider")
+
+    def initialize(self, evaluation_context: EvaluationContext) -> None:
+        # Preload locally-evaluated flag definitions only when the injected
+        # client is configured for local evaluation. We do not otherwise mutate
+        # the caller-owned client, and a preload failure must not make the
+        # OpenFeature client un-ready (remote evaluation still works).
+        if getattr(self._client, "personal_api_key", None):
+            try:
+                self._client.load_feature_flags()
+            except Exception:
+                # Don't block the OpenFeature client on a preload failure
+                # (remote evaluation still works), but surface it: an invalid
+                # personal_api_key, unreachable host, or missing permissions
+                # would otherwise silently disable local evaluation.
+                _logger.warning(
+                    "PostHogProvider: failed to preload feature flag "
+                    "definitions for local evaluation; falling back to remote "
+                    "evaluation.",
+                    exc_info=True,
+                )
+
+    def shutdown(self) -> None:
+        # The provider does not own the injected client's lifecycle, so this is
+        # deliberately a no-op. Callers shut down their own ``Posthog`` client.
+        return None
+
+    # -- core resolution ------------------------------------------------------
+
+    def _resolve(
+        self,
+        flag_key: str,
+        evaluation_context: Optional[EvaluationContext],
+    ) -> FeatureFlagResult:
+        distinct_id = self._distinct_id(evaluation_context)
+        person_properties, groups, group_properties = self._split_context(
+            evaluation_context
+        )
+        result = self._client.get_feature_flag_result(
+            flag_key,
+            distinct_id,
+            groups=groups or None,
+            person_properties=person_properties or None,
+            group_properties=group_properties or None,
+            send_feature_flag_events=self._send_feature_flag_events,
+        )
+        if result is None:
+            raise FlagNotFoundError(f"Flag '{flag_key}' not found or disabled.")
+        return result
+
+    # -- typed resolvers ------------------------------------------------------
+
+    def resolve_boolean_details(
+        self,
+        flag_key: str,
+        default_value: bool,
+        evaluation_context: Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[bool]:
+        result = self._resolve(flag_key, evaluation_context)
+        return self._details(result.enabled, result)
+
+    def resolve_string_details(
+        self,
+        flag_key: str,
+        default_value: str,
+        evaluation_context: Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[str]:
+        result = self._resolve(flag_key, evaluation_context)
+        if result.variant is None:
+            if not result.enabled:
+                # The user matched no condition / the flag is off. This is not a
+                # type error: return the caller's default with a normal reason.
+                return self._details(default_value, result)
+            # Enabled but no variant => a boolean flag read as a string. Surface
+            # a type mismatch so the caller gets its default per the OF spec
+            # rather than a surprising "True"/"False".
+            raise TypeMismatchError(
+                f"Flag '{flag_key}' has no string variant (boolean flag)."
+            )
+        return self._details(result.variant, result)
+
+    def resolve_integer_details(
+        self,
+        flag_key: str,
+        default_value: int,
+        evaluation_context: Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[int]:
+        return self._resolve_number(flag_key, default_value, evaluation_context, int)
+
+    def resolve_float_details(
+        self,
+        flag_key: str,
+        default_value: float,
+        evaluation_context: Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[float]:
+        return self._resolve_number(flag_key, default_value, evaluation_context, float)
+
+    def resolve_object_details(
+        self,
+        flag_key: str,
+        default_value: ObjectValue,
+        evaluation_context: Optional[EvaluationContext] = None,
+    ) -> FlagResolutionDetails[ObjectValue]:
+        result = self._resolve(flag_key, evaluation_context)
+        payload = result.payload  # already JSON-deserialized by posthog
+        if not isinstance(payload, (dict, list)):
+            if not result.enabled:
+                # Non-enrolled / disabled flag: return the default with a normal
+                # reason rather than flagging it as a type error.
+                return self._details(default_value, result)
+            # Matched flag with no object payload => a genuine type mismatch.
+            raise TypeMismatchError(f"Flag '{flag_key}' has no object/JSON payload.")
+        return self._details(payload, result)
+
+    def _resolve_number(
+        self,
+        flag_key: str,
+        default_value: _N,
+        evaluation_context: Optional[EvaluationContext],
+        ctor: Callable[[str], _N],
+    ) -> FlagResolutionDetails[_N]:
+        result = self._resolve(flag_key, evaluation_context)
+        if result.variant is None:
+            if not result.enabled:
+                # Non-enrolled / disabled flag: not a type error.
+                return self._details(default_value, result)
+            raise TypeMismatchError(
+                f"Flag '{flag_key}' has no variant to parse as {ctor.__name__}."
+            )
+        try:
+            value = ctor(result.variant)
+        except (TypeError, ValueError) as exc:
+            raise TypeMismatchError(
+                f"Flag '{flag_key}' variant '{result.variant}' is not a valid "
+                f"{ctor.__name__}."
+            ) from exc
+        return self._details(value, result)
+
+    def _details(
+        self, value: _T, result: FeatureFlagResult
+    ) -> FlagResolutionDetails[_T]:
+        """Build resolution details with our shared reason/metadata wiring."""
+        return FlagResolutionDetails(
+            value=value,
+            variant=result.variant,
+            reason=self._map_reason(result),
+            flag_metadata=self._flag_metadata(result),
+        )
+
+    # -- helpers --------------------------------------------------------------
+
+    def _distinct_id(self, evaluation_context: Optional[EvaluationContext]) -> str:
+        if evaluation_context is not None and evaluation_context.targeting_key:
+            return evaluation_context.targeting_key
+        if self._default_distinct_id is not None:
+            return self._default_distinct_id
+        raise TargetingKeyMissingError(
+            "No targeting_key in evaluation context and no default_distinct_id "
+            "configured."
+        )
+
+    @staticmethod
+    def _split_context(
+        evaluation_context: Optional[EvaluationContext],
+    ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
+        if evaluation_context is None or not evaluation_context.attributes:
+            return {}, {}, {}
+        attrs = evaluation_context.attributes
+        groups = attrs.get(GROUPS_KEY) or {}
+        group_properties = attrs.get(GROUP_PROPERTIES_KEY) or {}
+        person_properties = {k: v for k, v in attrs.items() if k not in _RESERVED_KEYS}
+        groups = groups if isinstance(groups, dict) else {}
+        group_properties = (
+            group_properties if isinstance(group_properties, dict) else {}
+        )
+        return person_properties, groups, group_properties
+
+    @staticmethod
+    def _map_reason(result: FeatureFlagResult) -> Reason:
+        """Map PostHog's free-text reason / enabled state to an OpenFeature Reason."""
+        if result.enabled:
+            # Enabled: the user matched a targeting condition (or was assigned a
+            # variant). PostHog has no distinct OpenFeature-style reason here.
+            return Reason.TARGETING_MATCH
+        # Not enabled. ``get_feature_flag_result`` returns ``None`` (surfaced as
+        # ``FlagNotFoundError`` one level up) for archived/non-existent flags, so
+        # a ``False`` result overwhelmingly means the flag is active but no
+        # targeting condition matched -> ``DEFAULT``. Only report ``DISABLED``
+        # (the flag itself is turned off) when the reason text says so.
+        text = (result.reason or "").lower()
+        if "disabled" in text:
+            return Reason.DISABLED
+        return Reason.DEFAULT
+
+    @staticmethod
+    def _flag_metadata(result: FeatureFlagResult) -> Mapping[str, Any]:
+        meta: dict[str, Any] = {}
+        if result.reason is not None:
+            meta["posthog_reason"] = result.reason
+        return meta

openfeature_provider_posthog-0.1.1.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: openfeature-provider-posthog
+Version: 0.1.1
+Summary: Official PostHog provider for the OpenFeature Python SDK.
+Author-email: PostHog <engineering@posthog.com>
+Maintainer-email: PostHog <engineering@posthog.com>
+License: MIT
+Project-URL: Homepage, https://github.com/posthog/posthog-python
+Project-URL: Repository, https://github.com/posthog/posthog-python
+Project-URL: Documentation, https://posthog.com/docs/feature-flags/installation/openfeature
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: posthog<8.0.0,>=7.0.0
+Requires-Dist: openfeature-sdk>=0.8.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file

openfeature_provider_posthog-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+openfeature/contrib/provider/posthog/__init__.py,sha256=XiSYl5BxJsrDAjtPJahMhFlS_3JwGk3VI2aVX5C9nBo,105
+openfeature/contrib/provider/posthog/provider.py,sha256=Pb14Db5mOEEu7MdvuBfYmWkAbg590_WxU9sFRTeZVnU,12092
+openfeature/contrib/provider/posthog/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openfeature_provider_posthog-0.1.1.dist-info/licenses/LICENSE,sha256=8MxuGvqoZjM-k3hKiV0PL1CENQpYiY5-C3-WHQZx7Bk,1073
+openfeature_provider_posthog-0.1.1.dist-info/METADATA,sha256=2vcI2vlImSu3OHcddePqzR9o6qUj5ZHHzIFUIywREs8,1232
+openfeature_provider_posthog-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+openfeature_provider_posthog-0.1.1.dist-info/top_level.txt,sha256=FF-_9FWc6friAIew3gd8t2010dOrnZA6KLxzgnWV22E,12
+openfeature_provider_posthog-0.1.1.dist-info/RECORD,,

openfeature_provider_posthog-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openfeature_provider_posthog-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2023 PostHog (part of Hiberly Inc)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openfeature_provider_posthog-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+openfeature