posthoganalytics 6.1.1__py3-none-any.whl → 6.3.0__py3-none-any.whl

posthoganalytics/__init__.py

@@ -676,7 +676,7 @@ def shutdown():
     _proxy("join")
 
 
-def setup():
+def setup() -> Client:
     global default_client
     if not default_client:
         if not api_key:
@@ -706,6 +706,8 @@ def setup():
     default_client.disabled = disabled
     default_client.debug = debug
 
+    return default_client
+
 
 def _proxy(method, *args, **kwargs):
     """Create an analytics client if one doesn't exist and send to it."""

posthoganalytics/ai/anthropic/anthropic.py

@@ -8,7 +8,7 @@ except ImportError:
 
 import time
 import uuid
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, cast
 
 from posthoganalytics.ai.utils import (
     call_llm_and_track_usage,
@@ -17,6 +17,7 @@ from posthoganalytics.ai.utils import (
     with_privacy_mode,
 )
 from posthoganalytics.client import Client as PostHogClient
+from posthoganalytics import setup
 
 
 class Anthropic(anthropic.Anthropic):
@@ -26,14 +27,14 @@ class Anthropic(anthropic.Anthropic):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         """
         Args:
             posthog_client: PostHog client for tracking usage
             **kwargs: Additional arguments passed to the Anthropic client
         """
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
         self.messages = WrappedMessages(self)
 
 

posthoganalytics/ai/anthropic/anthropic_async.py

@@ -10,6 +10,7 @@ import time
 import uuid
 from typing import Any, Dict, Optional
 
+from posthoganalytics import setup
 from posthoganalytics.ai.utils import (
     call_llm_and_track_usage_async,
     get_model_params,
@@ -26,14 +27,14 @@ class AsyncAnthropic(anthropic.AsyncAnthropic):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         """
         Args:
             posthog_client: PostHog client for tracking usage
             **kwargs: Additional arguments passed to the Anthropic client
         """
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
         self.messages = AsyncWrappedMessages(self)
 
 

posthoganalytics/ai/anthropic/anthropic_providers.py

@@ -5,9 +5,12 @@ except ImportError:
         "Please install the Anthropic SDK to use this feature: 'pip install anthropic'"
     )
 
+from typing import Optional
+
 from posthoganalytics.ai.anthropic.anthropic import WrappedMessages
 from posthoganalytics.ai.anthropic.anthropic_async import AsyncWrappedMessages
 from posthoganalytics.client import Client as PostHogClient
+from posthoganalytics import setup
 
 
 class AnthropicBedrock(anthropic.AnthropicBedrock):
@@ -17,9 +20,9 @@ class AnthropicBedrock(anthropic.AnthropicBedrock):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
         self.messages = WrappedMessages(self)
 
 
@@ -30,9 +33,9 @@ class AsyncAnthropicBedrock(anthropic.AsyncAnthropicBedrock):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
         self.messages = AsyncWrappedMessages(self)
 
 
@@ -43,9 +46,9 @@ class AnthropicVertex(anthropic.AnthropicVertex):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
         self.messages = WrappedMessages(self)
 
 
@@ -56,7 +59,7 @@ class AsyncAnthropicVertex(anthropic.AsyncAnthropicVertex):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
         self.messages = AsyncWrappedMessages(self)

posthoganalytics/ai/gemini/gemini.py

@@ -10,6 +10,7 @@ except ImportError:
         "Please install the Google Gemini SDK to use this feature: 'pip install google-genai'"
     )
 
+from posthoganalytics import setup
 from posthoganalytics.ai.utils import (
     call_llm_and_track_usage,
     get_model_params,
@@ -36,6 +37,8 @@ class Client:
         )
     """
 
+    _ph_client: PostHogClient
+
     def __init__(
         self,
         api_key: Optional[str] = None,
@@ -56,12 +59,14 @@ class Client:
             posthog_groups: Default groups for all calls (can be overridden per call)
             **kwargs: Additional arguments (for future compatibility)
         """
-        if posthog_client is None:
+        self._ph_client = posthog_client or setup()
+
+        if self._ph_client is None:
             raise ValueError("posthog_client is required for PostHog tracking")
 
         self.models = Models(
             api_key=api_key,
-            posthog_client=posthog_client,
+            posthog_client=self._ph_client,
             posthog_distinct_id=posthog_distinct_id,
             posthog_properties=posthog_properties,
             posthog_privacy_mode=posthog_privacy_mode,
@@ -97,10 +102,10 @@ class Models:
             posthog_groups: Default groups for all calls
             **kwargs: Additional arguments (for future compatibility)
         """
-        if posthog_client is None:
-            raise ValueError("posthog_client is required for PostHog tracking")
+        self._ph_client = posthog_client or setup()
 
-        self._ph_client = posthog_client
+        if self._ph_client is None:
+            raise ValueError("posthog_client is required for PostHog tracking")
 
         # Store default PostHog settings
         self._default_distinct_id = posthog_distinct_id

posthoganalytics/ai/langchain/callbacks.py

@@ -33,7 +33,7 @@ from langchain_core.messages import (
 from langchain_core.outputs import ChatGeneration, LLMResult
 from pydantic import BaseModel
 
-from posthoganalytics import default_client
+from posthoganalytics import setup
 from posthoganalytics.ai.utils import get_model_params, with_privacy_mode
 from posthoganalytics.client import Client
 
@@ -81,7 +81,7 @@ class CallbackHandler(BaseCallbackHandler):
     The PostHog LLM observability callback handler for LangChain.
     """
 
-    _client: Client
+    _ph_client: Client
     """PostHog client instance."""
 
     _distinct_id: Optional[Union[str, int, UUID]]
@@ -127,10 +127,7 @@ class CallbackHandler(BaseCallbackHandler):
             privacy_mode: Whether to redact the input and output of the trace.
             groups: Optional additional PostHog groups to use for the trace.
         """
-        posthog_client = client or default_client
-        if posthog_client is None:
-            raise ValueError("PostHog client is required")
-        self._client = posthog_client
+        self._ph_client = client or setup()
         self._distinct_id = distinct_id
         self._trace_id = trace_id
         self._properties = properties or {}
@@ -481,7 +478,7 @@ class CallbackHandler(BaseCallbackHandler):
         event_properties = {
             "$ai_trace_id": trace_id,
             "$ai_input_state": with_privacy_mode(
-                self._client, self._privacy_mode, run.input
+                self._ph_client, self._privacy_mode, run.input
             ),
             "$ai_latency": run.latency,
             "$ai_span_name": run.name,
@@ -497,13 +494,13 @@ class CallbackHandler(BaseCallbackHandler):
             event_properties["$ai_is_error"] = True
         elif outputs is not None:
             event_properties["$ai_output_state"] = with_privacy_mode(
-                self._client, self._privacy_mode, outputs
+                self._ph_client, self._privacy_mode, outputs
             )
 
         if self._distinct_id is None:
             event_properties["$process_person_profile"] = False
 
-        self._client.capture(
+        self._ph_client.capture(
             distinct_id=self._distinct_id or run_id,
             event=event_name,
             properties=event_properties,
@@ -550,14 +547,16 @@ class CallbackHandler(BaseCallbackHandler):
             "$ai_provider": run.provider,
             "$ai_model": run.model,
             "$ai_model_parameters": run.model_params,
-            "$ai_input": with_privacy_mode(self._client, self._privacy_mode, run.input),
+            "$ai_input": with_privacy_mode(
+                self._ph_client, self._privacy_mode, run.input
+            ),
             "$ai_http_status": 200,
             "$ai_latency": run.latency,
             "$ai_base_url": run.base_url,
         }
         if run.tools:
             event_properties["$ai_tools"] = with_privacy_mode(
-                self._client,
+                self._ph_client,
                 self._privacy_mode,
                 run.tools,
             )
@@ -589,7 +588,7 @@ class CallbackHandler(BaseCallbackHandler):
                     _extract_raw_esponse(generation) for generation in generation_result
                 ]
             event_properties["$ai_output_choices"] = with_privacy_mode(
-                self._client, self._privacy_mode, completions
+                self._ph_client, self._privacy_mode, completions
             )
 
         if self._properties:
@@ -598,7 +597,7 @@ class CallbackHandler(BaseCallbackHandler):
         if self._distinct_id is None:
             event_properties["$process_person_profile"] = False
 
-        self._client.capture(
+        self._ph_client.capture(
             distinct_id=self._distinct_id or trace_id,
             event="$ai_generation",
             properties=event_properties,

posthoganalytics/ai/openai/openai.py

@@ -15,6 +15,7 @@ from posthoganalytics.ai.utils import (
     with_privacy_mode,
 )
 from posthoganalytics.client import Client as PostHogClient
+from posthoganalytics import setup
 
 
 class OpenAI(openai.OpenAI):
@@ -24,16 +25,15 @@ class OpenAI(openai.OpenAI):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         """
         Args:
             api_key: OpenAI API key.
-            posthog_client: If provided, events will be captured via this client instead
-                            of the global posthog.
+            posthog_client: If provided, events will be captured via this client instead of the global `posthog`.
             **openai_config: Any additional keyword args to set on openai (e.g. organization="xxx").
         """
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
 
         # Store original objects after parent initialization (only if they exist)
         self._original_chat = getattr(self, "chat", None)

posthoganalytics/ai/openai/openai_async.py

@@ -1,6 +1,6 @@
 import time
 import uuid
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, cast
 
 try:
     import openai
@@ -9,6 +9,7 @@ except ImportError:
         "Please install the OpenAI SDK to use this feature: 'pip install openai'"
     )
 
+from posthoganalytics import setup
 from posthoganalytics.ai.utils import (
     call_llm_and_track_usage_async,
     get_model_params,
@@ -24,7 +25,7 @@ class AsyncOpenAI(openai.AsyncOpenAI):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         """
         Args:
             api_key: OpenAI API key.
@@ -33,7 +34,7 @@ class AsyncOpenAI(openai.AsyncOpenAI):
             **openai_config: Any additional keyword args to set on openai (e.g. organization="xxx").
         """
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
 
         # Store original objects after parent initialization (only if they exist)
         self._original_chat = getattr(self, "chat", None)

posthoganalytics/ai/openai/openai_providers.py

@@ -15,7 +15,10 @@ from posthoganalytics.ai.openai.openai_async import WrappedBeta as AsyncWrappedB
 from posthoganalytics.ai.openai.openai_async import WrappedChat as AsyncWrappedChat
 from posthoganalytics.ai.openai.openai_async import WrappedEmbeddings as AsyncWrappedEmbeddings
 from posthoganalytics.ai.openai.openai_async import WrappedResponses as AsyncWrappedResponses
+from typing import Optional
+
 from posthoganalytics.client import Client as PostHogClient
+from posthoganalytics import setup
 
 
 class AzureOpenAI(openai.AzureOpenAI):
@@ -25,7 +28,7 @@ class AzureOpenAI(openai.AzureOpenAI):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         """
         Args:
             api_key: Azure OpenAI API key.
@@ -34,7 +37,7 @@ class AzureOpenAI(openai.AzureOpenAI):
             **openai_config: Any additional keyword args to set on Azure OpenAI (e.g. azure_endpoint="xxx").
         """
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
 
         # Store original objects after parent initialization (only if they exist)
         self._original_chat = getattr(self, "chat", None)
@@ -63,7 +66,7 @@ class AsyncAzureOpenAI(openai.AsyncAzureOpenAI):
 
     _ph_client: PostHogClient
 
-    def __init__(self, posthog_client: PostHogClient, **kwargs):
+    def __init__(self, posthog_client: Optional[PostHogClient] = None, **kwargs):
         """
         Args:
             api_key: Azure OpenAI API key.
@@ -72,7 +75,7 @@ class AsyncAzureOpenAI(openai.AsyncAzureOpenAI):
             **openai_config: Any additional keyword args to set on Azure OpenAI (e.g. azure_endpoint="xxx").
         """
         super().__init__(**kwargs)
-        self._ph_client = posthog_client
+        self._ph_client = posthog_client or setup()
 
         # Store original objects after parent initialization (only if they exist)
         self._original_chat = getattr(self, "chat", None)

posthoganalytics/args.py

@@ -5,6 +5,8 @@ from datetime import datetime
 import numbers
 from uuid import UUID
 
+from posthoganalytics.types import SendFeatureFlagsOptions
+
 ID_TYPES = Union[numbers.Number, str, UUID, int]
 
 
@@ -22,7 +24,8 @@ class OptionalCaptureArgs(TypedDict):
             error ID if you capture an exception).
         groups: Group identifiers to associate with this event (format: {group_type: group_key})
         send_feature_flags: Whether to include currently active feature flags in the event properties.
-            Defaults to False
+            Can be a boolean (True/False) or a SendFeatureFlagsOptions object for advanced configuration.
+            Defaults to False.
         disable_geoip: Whether to disable GeoIP lookup for this event. Defaults to False.
     """
 
@@ -32,8 +35,8 @@ class OptionalCaptureArgs(TypedDict):
     uuid: NotRequired[Optional[str]]
     groups: NotRequired[Optional[Dict[str, str]]]
     send_feature_flags: NotRequired[
-        Optional[bool]
-    ]  # Optional so we can tell if the user is intentionally overriding a client setting or not
+        Optional[Union[bool, SendFeatureFlagsOptions]]
+    ]  # Updated to support both boolean and options object
     disable_geoip: NotRequired[
         Optional[bool]
     ]  # As above, optional so we can tell if the user is intentionally overriding a client setting or not

posthoganalytics/client.py

@@ -524,11 +524,31 @@ class Client(object):
 
         extra_properties: dict[str, Any] = {}
         feature_variants: Optional[dict[str, Union[bool, str]]] = {}
-        if send_feature_flags:
+
+        # Parse and normalize send_feature_flags parameter
+        flag_options = self._parse_send_feature_flags(send_feature_flags)
+
+        if flag_options["should_send"]:
             try:
-                feature_variants = self.get_feature_variants(
-                    distinct_id, groups, disable_geoip=disable_geoip
-                )
+                if flag_options["only_evaluate_locally"] is True:
+                    # Only use local evaluation
+                    feature_variants = self.get_all_flags(
+                        distinct_id,
+                        groups=(groups or {}),
+                        person_properties=flag_options["person_properties"],
+                        group_properties=flag_options["group_properties"],
+                        disable_geoip=disable_geoip,
+                        only_evaluate_locally=True,
+                    )
+                else:
+                    # Default behavior - use remote evaluation
+                    feature_variants = self.get_feature_variants(
+                        distinct_id,
+                        groups,
+                        person_properties=flag_options["person_properties"],
+                        group_properties=flag_options["group_properties"],
+                        disable_geoip=disable_geoip,
+                    )
             except Exception as e:
                 self.log.exception(
                     f"[FEATURE FLAGS] Unable to get feature variants: {e}"
@@ -559,6 +579,42 @@ class Client(object):
 
         return self._enqueue(msg, disable_geoip)
 
+    def _parse_send_feature_flags(self, send_feature_flags) -> dict:
+        """
+        Parse and normalize send_feature_flags parameter into a standard format.
+
+        Args:
+            send_feature_flags: Either bool or SendFeatureFlagsOptions dict
+
+        Returns:
+            dict: Normalized options with keys: should_send, only_evaluate_locally,
+                  person_properties, group_properties
+
+        Raises:
+            TypeError: If send_feature_flags is not bool or dict
+        """
+        if isinstance(send_feature_flags, dict):
+            return {
+                "should_send": True,
+                "only_evaluate_locally": send_feature_flags.get(
+                    "only_evaluate_locally"
+                ),
+                "person_properties": send_feature_flags.get("person_properties"),
+                "group_properties": send_feature_flags.get("group_properties"),
+            }
+        elif isinstance(send_feature_flags, bool):
+            return {
+                "should_send": send_feature_flags,
+                "only_evaluate_locally": None,
+                "person_properties": None,
+                "group_properties": None,
+            }
+        else:
+            raise TypeError(
+                f"Invalid type for send_feature_flags: {type(send_feature_flags)}. "
+                f"Expected bool or dict."
+            )
+
     def set(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
         """
         Set properties on a person profile.

posthoganalytics/test/test_client.py

@@ -751,6 +751,186 @@ class TestClient(unittest.TestCase):
 
             self.assertEqual(patch_flags.call_count, 0)
 
+    @mock.patch("posthog.client.flags")
+    def test_capture_with_send_feature_flags_options_only_evaluate_locally_true(
+        self, patch_flags
+    ):
+        """Test that SendFeatureFlagsOptions with only_evaluate_locally=True uses local evaluation"""
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                personal_api_key=FAKE_TEST_API_KEY,
+                sync_mode=True,
+            )
+
+            # Set up local flags
+            client.feature_flags = [
+                {
+                    "id": 1,
+                    "key": "local-flag",
+                    "active": True,
+                    "filters": {
+                        "groups": [
+                            {
+                                "properties": [{"key": "region", "value": "US"}],
+                                "rollout_percentage": 100,
+                            }
+                        ],
+                    },
+                }
+            ]
+
+            send_options = {
+                "only_evaluate_locally": True,
+                "person_properties": {"region": "US"},
+            }
+
+            msg_uuid = client.capture(
+                "test event", distinct_id="distinct_id", send_feature_flags=send_options
+            )
+
+            self.assertIsNotNone(msg_uuid)
+            self.assertFalse(self.failed)
+
+            # Verify flags() was not called (no remote evaluation)
+            patch_flags.assert_not_called()
+
+            # Check the message includes the local flag
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            msg = batch_data[0]
+
+            self.assertEqual(msg["properties"]["$feature/local-flag"], True)
+            self.assertEqual(msg["properties"]["$active_feature_flags"], ["local-flag"])
+
+    @mock.patch("posthog.client.flags")
+    def test_capture_with_send_feature_flags_options_only_evaluate_locally_false(
+        self, patch_flags
+    ):
+        """Test that SendFeatureFlagsOptions with only_evaluate_locally=False forces remote evaluation"""
+        patch_flags.return_value = {"featureFlags": {"remote-flag": "remote-value"}}
+
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                personal_api_key=FAKE_TEST_API_KEY,
+                sync_mode=True,
+            )
+
+            send_options = {
+                "only_evaluate_locally": False,
+                "person_properties": {"plan": "premium"},
+                "group_properties": {"company": {"type": "enterprise"}},
+            }
+
+            msg_uuid = client.capture(
+                "test event",
+                distinct_id="distinct_id",
+                groups={"company": "acme"},
+                send_feature_flags=send_options,
+            )
+
+            self.assertIsNotNone(msg_uuid)
+            self.assertFalse(self.failed)
+
+            # Verify flags() was called with the correct properties
+            patch_flags.assert_called_once()
+            call_args = patch_flags.call_args[1]
+            self.assertEqual(call_args["person_properties"], {"plan": "premium"})
+            self.assertEqual(
+                call_args["group_properties"], {"company": {"type": "enterprise"}}
+            )
+
+            # Check the message includes the remote flag
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            msg = batch_data[0]
+
+            self.assertEqual(msg["properties"]["$feature/remote-flag"], "remote-value")
+
+    @mock.patch("posthog.client.flags")
+    def test_capture_with_send_feature_flags_options_default_behavior(
+        self, patch_flags
+    ):
+        """Test that SendFeatureFlagsOptions without only_evaluate_locally defaults to remote evaluation"""
+        patch_flags.return_value = {"featureFlags": {"default-flag": "default-value"}}
+
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                personal_api_key=FAKE_TEST_API_KEY,
+                sync_mode=True,
+            )
+
+            send_options = {
+                "person_properties": {"subscription": "pro"},
+            }
+
+            msg_uuid = client.capture(
+                "test event", distinct_id="distinct_id", send_feature_flags=send_options
+            )
+
+            self.assertIsNotNone(msg_uuid)
+            self.assertFalse(self.failed)
+
+            # Verify flags() was called (default to remote evaluation)
+            patch_flags.assert_called_once()
+            call_args = patch_flags.call_args[1]
+            self.assertEqual(call_args["person_properties"], {"subscription": "pro"})
+
+            # Check the message includes the flag
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            msg = batch_data[0]
+
+            self.assertEqual(
+                msg["properties"]["$feature/default-flag"], "default-value"
+            )
+
+    @mock.patch("posthog.client.flags")
+    def test_capture_exception_with_send_feature_flags_options(self, patch_flags):
+        """Test that capture_exception also supports SendFeatureFlagsOptions"""
+        patch_flags.return_value = {"featureFlags": {"exception-flag": True}}
+
+        with mock.patch("posthog.client.batch_post") as mock_post:
+            client = Client(
+                FAKE_TEST_API_KEY,
+                on_error=self.set_fail,
+                personal_api_key=FAKE_TEST_API_KEY,
+                sync_mode=True,
+            )
+
+            send_options = {
+                "only_evaluate_locally": False,
+                "person_properties": {"user_type": "admin"},
+            }
+
+            try:
+                raise ValueError("Test exception")
+            except ValueError as e:
+                msg_uuid = client.capture_exception(
+                    e, distinct_id="distinct_id", send_feature_flags=send_options
+                )
+
+            self.assertIsNotNone(msg_uuid)
+            self.assertFalse(self.failed)
+
+            # Verify flags() was called with the correct properties
+            patch_flags.assert_called_once()
+            call_args = patch_flags.call_args[1]
+            self.assertEqual(call_args["person_properties"], {"user_type": "admin"})
+
+            # Check the message includes the flag
+            mock_post.assert_called_once()
+            batch_data = mock_post.call_args[1]["batch"]
+            msg = batch_data[0]
+
+            self.assertEqual(msg["event"], "$exception")
+            self.assertEqual(msg["properties"]["$feature/exception-flag"], True)
+
     def test_stringifies_distinct_id(self):
         # A large number that loses precision in node:
         # node -e "console.log(157963456373623802 + 1)" > 157963456373623800
@@ -1591,7 +1771,7 @@ class TestClient(unittest.TestCase):
 
     @mock.patch("posthog.client.Poller")
     @mock.patch("posthog.client.get")
-    def test_call_identify_fails(self, patch_get, patch_poll):
+    def test_call_identify_fails(self, patch_get, patch_poller):
         def raise_effect():
             raise Exception("http exception")
 
@@ -1993,3 +2173,76 @@ class TestClient(unittest.TestCase):
         result = client.get_remote_config_payload("test-flag")
 
         self.assertIsNone(result)
+
+    def test_parse_send_feature_flags_method(self):
+        """Test the _parse_send_feature_flags helper method"""
+        client = Client(FAKE_TEST_API_KEY, sync_mode=True)
+
+        # Test boolean True
+        result = client._parse_send_feature_flags(True)
+        expected = {
+            "should_send": True,
+            "only_evaluate_locally": None,
+            "person_properties": None,
+            "group_properties": None,
+        }
+        self.assertEqual(result, expected)
+
+        # Test boolean False
+        result = client._parse_send_feature_flags(False)
+        expected = {
+            "should_send": False,
+            "only_evaluate_locally": None,
+            "person_properties": None,
+            "group_properties": None,
+        }
+        self.assertEqual(result, expected)
+
+        # Test options dict with all fields
+        options = {
+            "only_evaluate_locally": True,
+            "person_properties": {"plan": "premium"},
+            "group_properties": {"company": {"type": "enterprise"}},
+        }
+        result = client._parse_send_feature_flags(options)
+        expected = {
+            "should_send": True,
+            "only_evaluate_locally": True,
+            "person_properties": {"plan": "premium"},
+            "group_properties": {"company": {"type": "enterprise"}},
+        }
+        self.assertEqual(result, expected)
+
+        # Test options dict with partial fields
+        options = {"person_properties": {"user_id": "123"}}
+        result = client._parse_send_feature_flags(options)
+        expected = {
+            "should_send": True,
+            "only_evaluate_locally": None,
+            "person_properties": {"user_id": "123"},
+            "group_properties": None,
+        }
+        self.assertEqual(result, expected)
+
+        # Test empty dict
+        result = client._parse_send_feature_flags({})
+        expected = {
+            "should_send": True,
+            "only_evaluate_locally": None,
+            "person_properties": None,
+            "group_properties": None,
+        }
+        self.assertEqual(result, expected)
+
+        # Test invalid types
+        with self.assertRaises(TypeError) as cm:
+            client._parse_send_feature_flags("invalid")
+        self.assertIn("Invalid type for send_feature_flags", str(cm.exception))
+
+        with self.assertRaises(TypeError) as cm:
+            client._parse_send_feature_flags(123)
+        self.assertIn("Invalid type for send_feature_flags", str(cm.exception))
+
+        with self.assertRaises(TypeError) as cm:
+            client._parse_send_feature_flags(None)
+        self.assertIn("Invalid type for send_feature_flags", str(cm.exception))

posthoganalytics/types.py

@@ -9,6 +9,24 @@ FlagValue = Union[bool, str]
 BeforeSendCallback = Callable[[dict[str, Any]], Optional[dict[str, Any]]]
 
 
+class SendFeatureFlagsOptions(TypedDict, total=False):
+    """Options for sending feature flags with capture events.
+
+    Args:
+        only_evaluate_locally: Whether to only use local evaluation for feature flags.
+            If True, only flags that can be evaluated locally will be included.
+            If False, remote evaluation via /flags API will be used when needed.
+        person_properties: Properties to use for feature flag evaluation specific to this event.
+            These properties will be merged with any existing person properties.
+        group_properties: Group properties to use for feature flag evaluation specific to this event.
+            Format: { group_type_name: { group_properties } }
+    """
+
+    only_evaluate_locally: Optional[bool]
+    person_properties: Optional[dict[str, Any]]
+    group_properties: Optional[dict[str, dict[str, Any]]]
+
+
 @dataclass(frozen=True)
 class FlagReason:
     code: str

posthoganalytics/version.py

@@ -1,4 +1,4 @@
-VERSION = "6.1.1"
+VERSION = "6.3.0"
 
 if __name__ == "__main__":
     print(VERSION, end="")  # noqa: T201

{posthoganalytics-6.1.1.dist-info → posthoganalytics-6.3.0.dist-info}/METADATA

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

{posthoganalytics-6.1.1.dist-info → posthoganalytics-6.3.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
-posthoganalytics/__init__.py,sha256=TSi-Hq6mKCAiq6VAjaHPG5g8Pb8FTkK8De_l69O7G74,24096
-posthoganalytics/args.py,sha256=hRKPQ3cPGyDn4S7Ay9t2NlgoZg1cJ0GeN_Mb6OKtmfo,3145
-posthoganalytics/client.py,sha256=L_Ive-qlIvflqjLrote0TP2r9jBqbNsQE_Xs7gDEe4Y,65265
+posthoganalytics/__init__.py,sha256=N_Mq_RDLFbd02HCMWxJPTtcSYj3NWcartohQKa7MNlw,24133
+posthoganalytics/args.py,sha256=iZ2JWeANiAREJKhS-Qls9tIngjJOSfAVR8C4xFT5sHw,3307
+posthoganalytics/client.py,sha256=y7bUrKYaCGPWnAkOfYrLEVFD7Buoc4dZor6yKB51O_E,67611
 posthoganalytics/consumer.py,sha256=CiNbJBdyW9jER3ZYCKbX-JFmEDXlE1lbDy1MSl43-a0,4617
 posthoganalytics/contexts.py,sha256=LFSFIYpUFWKTBnGMjV9n1aYHWbAzz5zLJGr2qG34PoE,9405
 posthoganalytics/exception_capture.py,sha256=1VHBfffrXXrkK0PT8iVgKPpj_R1pGAzG5f3Qw0WF79w,1783
@@ -9,28 +9,28 @@ posthoganalytics/feature_flags.py,sha256=O_kXmw3goB2E9XMBosdPeBAuo9MsnsH8PyNWq95
 posthoganalytics/poller.py,sha256=jBz5rfH_kn_bBz7wCB46Fpvso4ttx4uzqIZWvXBCFmQ,595
 posthoganalytics/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 posthoganalytics/request.py,sha256=TaeySYpcvHMf5Ftf5KqqlO0VPJpirKBCRrThlS04Kew,6124
-posthoganalytics/types.py,sha256=INxWBOEQc0xgPcap6FdQNSU7zuQBmKShYaGzyuHKql8,9128
+posthoganalytics/types.py,sha256=2rwhiZd9lvs37MiXEBADVdMKvcCvFXfAMgIUJ8KNTBs,10005
 posthoganalytics/utils.py,sha256=-0w-OLcCaoldkbBebPzQyBzLJSo9G9yBOg8NDVz7La8,16088
-posthoganalytics/version.py,sha256=xZhcgW3hzlFW0J_tV0DpBWXhz8E1uxHP1x46lky-cjo,87
+posthoganalytics/version.py,sha256=kh3XbIm02A3duSxLSxM9UICZfLJm0YJYGYgmKSdH210,87
 posthoganalytics/ai/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 posthoganalytics/ai/utils.py,sha256=5-2XfmetCs0v9otBoux7-IEG933wAnKLSGS6oYLqCkw,19529
 posthoganalytics/ai/anthropic/__init__.py,sha256=fFhDOiRzTXzGQlgnrRDL-4yKC8EYIl8NW4a2QNR6xRU,368
-posthoganalytics/ai/anthropic/anthropic.py,sha256=5YekQFUio_SRMgdI2y7gbEKFrp-dk1Vi333662doRxc,7328
-posthoganalytics/ai/anthropic/anthropic_async.py,sha256=4ncBLLhhPUQ46XzHz6YRlBt-jBBdP6ol-6V_78AmdAY,7448
-posthoganalytics/ai/anthropic/anthropic_providers.py,sha256=6gnL_Z43FTar2TGNPDudPXEZawpQfVx7zO4cLndz9r4,1963
+posthoganalytics/ai/anthropic/anthropic.py,sha256=P8o-pZ2rbJXDiHO73OWjO7OgboGiEm_wVY4pbvHnUEs,7397
+posthoganalytics/ai/anthropic/anthropic_async.py,sha256=iAwVlAY6VeW0dGZdMkdfniBTBFUdZZrDMZi-O9vdiuo,7511
+posthoganalytics/ai/anthropic/anthropic_providers.py,sha256=y1_qc8Lbip-YDmpimPGg3DfTm5g-WZk5FrRCXzwF_Ow,2139
 posthoganalytics/ai/gemini/__init__.py,sha256=bMNBnJ6NO_PCQCwmxKIiw4adFuEQ06hFFBALt-aDW-0,174
-posthoganalytics/ai/gemini/gemini.py,sha256=NmVfsG3VaTmDoNCIqXgw2n48H-00zHKfqVY46WFPbEI,13152
+posthoganalytics/ai/gemini/gemini.py,sha256=oi7VIPJLMEHPqRQwvAGwLjkaF0RZhvloCqOJgsQrmJ8,13285
 posthoganalytics/ai/langchain/__init__.py,sha256=9CqAwLynTGj3ASAR80C3PmdTdrYGmu99tz0JL-HPFgI,70
-posthoganalytics/ai/langchain/callbacks.py,sha256=qZlHsD8QJiXbvykBIDvNlPa0lQS4zXaxTmZ0R9JHpDQ,28848
+posthoganalytics/ai/langchain/callbacks.py,sha256=nfLRbAOajQ6DVSCedUUnemY3uS_icTeILEhfnSAUJ4U,28755
 posthoganalytics/ai/openai/__init__.py,sha256=_flZxkyaDZme9hxJsY31sMlq4nP1dtc75HmNgj-21Kg,197
-posthoganalytics/ai/openai/openai.py,sha256=iL_cwctaAhPdXNo4EpIZooOWGyjNj0W-OUEoLchTj9s,23394
-posthoganalytics/ai/openai/openai_async.py,sha256=KxPCd5imF5iZ9VkJ12HjCO2skaF1tHsHveAknIqV93g,23769
-posthoganalytics/ai/openai/openai_providers.py,sha256=EMuEvdHSOFbrhmfuU0is7pBVWS3ReAUT0PZqgMXdyjk,3884
+posthoganalytics/ai/openai/openai.py,sha256=6bC3OxH9TP7EFkCGQRfxfcormVTAwLP4Wfj3ID3RwEc,23431
+posthoganalytics/ai/openai/openai_async.py,sha256=0gEhTr-ePiOhS8h1WznQDSz_lJm1aferk5K1ZAMo-K0,23838
+posthoganalytics/ai/openai/openai_providers.py,sha256=RPVmj2V0_lAdno_ax5Ul2kwhBA9_rRgAdl_sCqrQc6M,4004
 posthoganalytics/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 posthoganalytics/integrations/django.py,sha256=KYtBr7CkiZQynRc2TCWWYHe-J3ie8iSUa42WPshYZdc,6795
 posthoganalytics/test/__init__.py,sha256=VYgM6xPbJbvS-xhIcDiBRs0MFC9V_jT65uNeerCz_rM,299
 posthoganalytics/test/test_before_send.py,sha256=A1_UVMewhHAvO39rZDWfS606vG_X-q0KNXvh5DAKiB8,7930
-posthoganalytics/test/test_client.py,sha256=fghypNGUqOY9OmycsdNK5SsyCoimxYVisFfFq2nkTCU,77840
+posthoganalytics/test/test_client.py,sha256=RJURSog8fX_YEBzv4MGrX1amX0Ma7NUMlwSanfgORmQ,87343
 posthoganalytics/test/test_consumer.py,sha256=HGMfU9PzQ5ZAe_R3kHnZNsMvD7jUjHL-gie0isrvMMk,7107
 posthoganalytics/test/test_contexts.py,sha256=c--hNUIEf6SHQ7H9vdPhU1oLCN0SnD4wDbFr-eLPHDo,7013
 posthoganalytics/test/test_exception_capture.py,sha256=al37Kg6wjzL_IBCFUUXRvkP6nVrqS6IZRCOKSo29Nh8,1063
@@ -42,8 +42,8 @@ posthoganalytics/test/test_request.py,sha256=Zc0VbkjpVmj8mKokQm9rzdgTr0b1U44vvMY
 posthoganalytics/test/test_size_limited_dict.py,sha256=-5IQjIEr_-Dql24M0HusdR_XroOMrtgiT0v6ZQCRvzo,774
 posthoganalytics/test/test_types.py,sha256=bRPHdwVpP7hu7emsplU8UVyzSQptv6PaG5lAoOD_BtM,7595
 posthoganalytics/test/test_utils.py,sha256=sqUTbfweVcxxFRd3WDMFXqPMyU6DvzOBeAOc68Py9aw,9620
-posthoganalytics-6.1.1.dist-info/licenses/LICENSE,sha256=wGf9JBotDkSygFj43m49oiKlFnpMnn97keiZKF-40vE,2450
-posthoganalytics-6.1.1.dist-info/METADATA,sha256=xrhfLBXcqwgMm1nsVsP5UDPo3nrGC6IZitVt0Dpn5XM,6024
-posthoganalytics-6.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-posthoganalytics-6.1.1.dist-info/top_level.txt,sha256=8QsNIqIkBh1p2TXvKp0Em9ZLZKwe3uIqCETyW4s1GOE,17
-posthoganalytics-6.1.1.dist-info/RECORD,,
+posthoganalytics-6.3.0.dist-info/licenses/LICENSE,sha256=wGf9JBotDkSygFj43m49oiKlFnpMnn97keiZKF-40vE,2450
+posthoganalytics-6.3.0.dist-info/METADATA,sha256=TyFn8t0pOnWbsC11Y3J-iJM50uiDgdQwsmmz9gKmvCw,6024
+posthoganalytics-6.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+posthoganalytics-6.3.0.dist-info/top_level.txt,sha256=8QsNIqIkBh1p2TXvKp0Em9ZLZKwe3uIqCETyW4s1GOE,17
+posthoganalytics-6.3.0.dist-info/RECORD,,