feat!: super_options, context options and personless as the lowest option layer

Author: eli-r-ph

posthog/__init__.py

@@ -52,6 +52,12 @@
 from posthog.contexts import (
     get_tags as inner_get_tags,
 )
+from posthog.contexts import (
+    set_context_option as inner_set_context_option,
+)
+from posthog.contexts import (
+    get_context_options as inner_get_context_options,
+)
 from posthog.exception_utils import (
     DEFAULT_CODE_VARIABLES_DETECT_SECRETS,
     DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS,
@@ -299,6 +305,43 @@ def get_tags() -> Dict[str, Any]:
     return inner_get_tags()
 
 
+def set_context_option(key: str, value: Any) -> None:
+    """
+    Set a capture option for every event captured within the current context.
+
+    Context options override ``super_options``, and an event's own ``options``
+    override context options.
+
+    Args:
+        key: The option name, such as ``"process_person_profile"``
+        value: The option value, sent as given
+
+    Examples:
+        ```python
+        from posthog import new_context, set_context_option
+        with new_context():
+            set_context_option("process_person_profile", False)
+        ```
+
+    Category:
+        Contexts
+    """
+    return inner_set_context_option(key, value)
+
+
+def get_context_options() -> Dict[str, Any]:
+    """
+    Get all capture options from the current context.
+
+    Returns:
+        Dict of all capture options in the current context
+
+    Category:
+        Contexts
+    """
+    return inner_get_context_options()
+
+
 """Settings.
 
 These module-level settings configure the legacy global PostHog client used by
@@ -340,7 +383,11 @@ def get_tags() -> Dict[str, Any]:
     feature_flags_request_max_retries: Number of retries for feature flag
         requests after network, transport, or timeout failures. Defaults to 1.
         Set to 0 to disable retries.
-    super_properties: Properties merged into every captured event.
+    super_properties: Properties for every captured event. Context tags and
+        an event's own properties override them.
+    super_options: Capture options for every captured event, such as
+        ``{"cookieless_mode": True}``. Context options and an event's own
+        ``options`` override them.
     metrics: Config dict for the ``client.metrics`` API (``service_name``,
         ``service_version``, ``environment``, ``flush_interval``, ...). Applied
         when ``setup()`` builds the global client, or on a later ``setup()``
@@ -414,6 +461,7 @@ def get_tags() -> Dict[str, Any]:
 feature_flags_request_timeout_seconds = 3  # type: int
 feature_flags_request_max_retries = 1  # type: int
 super_properties = None  # type: Optional[Dict]
+super_options = None  # type: Optional[Dict]
 metrics = None  # type: Optional[Dict]
 traces = None  # type: Optional[Dict]
 enable_exception_autocapture = False  # type: bool
@@ -1406,6 +1454,7 @@ def setup() -> Client:
             feature_flags_request_timeout_seconds=feature_flags_request_timeout_seconds,
             feature_flags_request_max_retries=feature_flags_request_max_retries,
             super_properties=super_properties,
+            super_options=super_options,
             metrics=metrics,
             traces=traces,
             # TODO: Currently this monitoring begins only when the Client is initialised (which happens when you do something with the SDK)

posthog/async_client.py

@@ -43,6 +43,7 @@
     Client as _SyncClient,
     _metadata_has_experiment,
     _parse_flag_payload,
+    _personless_options,
     add_context_tags as _add_context_tags,
     get_identity_state as _get_identity_state,
     stringify_id as _stringify_id,
@@ -55,6 +56,7 @@
     get_code_variables_mask_url_credentials_context,
     get_context_device_id as _get_context_device_id,
     get_context_distinct_id as _get_context_distinct_id,
+    get_context_options as _get_context_options,
     get_context_session_id as _get_context_session_id,
 )
 from .exception_utils import (
@@ -120,6 +122,7 @@ def __init__(
         is_server: bool = True,
         historical_migration: bool = False,
         super_properties: Optional[dict[str, Any]] = None,
+        super_options: Optional[dict[str, Any]] = None,
         before_send=None,
         log_captured_exceptions: bool = False,
         project_root: Optional[str] = None,
@@ -154,6 +157,7 @@ def __init__(
         self.is_server = is_server
         self.historical_migration = historical_migration
         self.super_properties = super_properties
+        self.super_options = super_options
         self._release_id = _resolve_release_id()
         self.capture_compression = _resolve_capture_compression(capture_compression)
         self.capture_trace_context = capture_trace_context
@@ -397,6 +401,7 @@ def _prepare_event(
         msg: dict[str, Any],
         disable_geoip: Optional[bool],
         property_allowlist=None,
+        derived_options: Optional[dict[str, Any]] = None,
     ) -> tuple[Optional[dict[str, Any]], Optional[str]]:
         if self.disabled or not self._accepting:
             return None, None
@@ -423,7 +428,14 @@ def _prepare_event(
         if disable_geoip:
             properties["$geoip_disable"] = True
         if self.super_properties:
-            msg["properties"] = {**properties, **self.super_properties}
+            msg["properties"] = {**self.super_properties, **properties}
+        # Each layer overrides the one before it: values the SDK derives, such
+        # as personless, then super options, then context and event options.
+        msg["options"] = {
+            **(derived_options or {}),
+            **_event_options(self.super_options),
+            **(msg.get("options") or {}),
+        }
         if self._release_id is not None:
             msg["properties"].setdefault("$release_id", self._release_id)
         if self.is_server:
@@ -460,16 +472,14 @@ async def _process_event(self, msg: dict[str, Any]) -> Optional[dict[str, Any]]:
 
     def _build_capture_event(
         self, event: str, kwargs: OptionalCaptureArgs
-    ) -> tuple[dict[str, Any], Optional[bool], Any]:
+    ) -> tuple[dict[str, Any], Optional[bool], Any, dict[str, Any]]:
         properties = {**(kwargs.get("properties") or {}), **system_context()}
         if self.capture_trace_context:
             properties = {**_get_current_otel_span_properties(), **properties}
         properties = _add_context_tags(properties)
         assert properties is not None
 
         distinct_id, personless = _get_identity_state(kwargs.get("distinct_id"))
-        if personless and "$process_person_profile" not in properties:
-            properties["$process_person_profile"] = False
         groups = kwargs.get("groups")
         if groups:
             properties["$groups"] = groups
@@ -493,22 +503,26 @@ def _build_capture_event(
                 "distinct_id": distinct_id,
                 "event": event,
                 "uuid": kwargs.get("uuid"),
-                "options": _event_options(kwargs.get("options")),
+                "options": {
+                    **_get_context_options(),
+                    **_event_options(kwargs.get("options")),
+                },
             },
             kwargs.get("disable_geoip"),
             kwargs.get("_property_allowlist"),
+            _personless_options(personless),
         )
 
     def capture(
         self, event: str, **kwargs: Unpack[OptionalCaptureArgs]
     ) -> Optional[str]:
         """Queue an event without blocking for network delivery."""
         try:
-            msg, disable_geoip, property_allowlist = self._build_capture_event(
-                event, kwargs
+            msg, disable_geoip, property_allowlist, derived_options = (
+                self._build_capture_event(event, kwargs)
             )
             prepared, sent_uuid = self._prepare_event(
-                msg, disable_geoip, property_allowlist
+                msg, disable_geoip, property_allowlist, derived_options
             )
             if prepared is None or sent_uuid is None:
                 return None
@@ -551,11 +565,11 @@ async def capture_immediate(
         self._immediate_callers[current] = self._immediate_callers.get(current, 0) + 1
         error_batch: list[dict[str, Any]] = []
         try:
-            msg, disable_geoip, property_allowlist = self._build_capture_event(
-                event, kwargs
+            msg, disable_geoip, property_allowlist, derived_options = (
+                self._build_capture_event(event, kwargs)
             )
             prepared, sent_uuid = self._prepare_event(
-                msg, disable_geoip, property_allowlist
+                msg, disable_geoip, property_allowlist, derived_options
             )
             if prepared is None or sent_uuid is None:
                 return None
@@ -612,7 +626,10 @@ def _build_person_properties_event(
             property_key: properties,
             "event": event,
             "uuid": kwargs.get("uuid"),
-            "options": _event_options(kwargs.get("options")),
+            "options": {
+                **_get_context_options(),
+                **_event_options(kwargs.get("options")),
+            },
         }
 
     def set(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:

posthog/client.py

@@ -51,11 +51,13 @@
     get_context_device_id,
     get_context_distinct_id,
     get_context_session_id,
+    get_context_options as _context_get_context_options,
     get_tags as _context_get_tags,
     identify_context as _context_identify_context,
     _scoped as _context_scoped,
     new_context,
     set_context_device_id as _context_set_context_device_id,
+    set_context_option as _context_set_context_option,
     set_context_session as _context_set_context_session,
     tag as _context_tag,
 )
@@ -270,6 +272,11 @@ def _stringify_event_uuid(value) -> str:
     return canonical
 
 
+def _personless_options(personless: bool) -> dict[str, Any]:
+    """The lowest option layer: no person profile for a generated distinct ID."""
+    return {"process_person_profile": False} if personless else {}
+
+
 def add_context_tags(properties):
     properties = properties or {}
     current_context = _get_current_context()
@@ -706,6 +713,7 @@ def __init__(
         feature_flags_request_timeout_seconds=3,
         feature_flags_request_max_retries=1,
         super_properties=None,
+        super_options=None,
         enable_exception_autocapture=False,
         log_captured_exceptions=False,
         project_root=None,
@@ -791,7 +799,11 @@ def __init__(
             feature_flags_request_max_retries: Number of retries for feature flag
                 requests after network, transport, or timeout failures. Defaults
                 to 1. Set to 0 to disable retries.
-            super_properties: Properties merged into every captured event.
+            super_properties: Properties for every captured event. Context
+                tags and an event's own properties override them.
+            super_options: Capture options for every captured event, such as
+                ``{"cookieless_mode": True}``. Context options and an event's
+                own ``options`` override them.
             enable_exception_autocapture: Automatically capture uncaught
                 exceptions.
             log_captured_exceptions: Also log exceptions captured by error
@@ -999,6 +1011,7 @@ def __init__(
             maximum=AI_MAX_MSG_SIZE,
         )
         self.super_properties = super_properties
+        self.super_options = super_options
         # Release id from POSTHOG_RELEASE_ID, attached to every event. Resolved
         # here so the env var is read once per client.
         self._release_id = _resolve_release_id()
@@ -1311,6 +1324,31 @@ def get_tags(self) -> Dict[str, Any]:
         """
         return _context_get_tags()
 
+    def set_context_option(self, key: str, value: Any) -> None:
+        """
+        Set a capture option for every event captured within the current context.
+
+        Args:
+            key: The option name, such as ``"process_person_profile"``.
+            value: The option value, sent as given.
+
+        Category:
+            Contexts
+        """
+        _context_set_context_option(key, value)
+
+    def get_context_options(self) -> Dict[str, Any]:
+        """
+        Get all capture options from the current context.
+
+        Returns:
+            Dict of all capture options in the current context.
+
+        Category:
+            Contexts
+        """
+        return _context_get_context_options()
+
     def identify_context(self, distinct_id: str) -> None:
         """
         Identify the current context with a distinct ID.
@@ -1707,7 +1745,10 @@ def _capture(
         flags_snapshot = kwargs.get("flags", None)
         send_feature_flags = kwargs.get("send_feature_flags", False)
         disable_geoip = kwargs.get("disable_geoip", None)
-        options = _event_options(kwargs.get("options", None))
+        options = {
+            **_context_get_context_options(),
+            **_event_options(kwargs.get("options", None)),
+        }
         # Internal, set for minimal $feature_flag_called events: a strict allowlist
         # applied to the fully-enriched properties dict just before enqueueing.
         property_allowlist = kwargs.get("_property_allowlist", None)
@@ -1722,9 +1763,6 @@ def _capture(
 
         (distinct_id, personless) = get_identity_state(distinct_id)
 
-        if personless and "$process_person_profile" not in properties:
-            properties["$process_person_profile"] = False
-
         msg = {
             "properties": properties,
             "timestamp": timestamp,
@@ -1829,7 +1867,11 @@ def _capture(
             msg["properties"] = properties
 
         return self._enqueue(
-            msg, disable_geoip, lane, property_allowlist=property_allowlist
+            msg,
+            disable_geoip,
+            lane,
+            property_allowlist=property_allowlist,
+            derived_options=_personless_options(personless),
         )
 
     def _parse_send_feature_flags(self, send_feature_flags) -> SendFeatureFlagsOptions:
@@ -1917,7 +1959,10 @@ def set(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
             "$set": properties,
             "event": "$set",
             "uuid": uuid,
-            "options": _event_options(kwargs.get("options", None)),
+            "options": {
+                **_context_get_context_options(),
+                **_event_options(kwargs.get("options", None)),
+            },
         }
 
         return self._enqueue(msg, disable_geoip)
@@ -1967,7 +2012,10 @@ def set_once(self, **kwargs: Unpack[OptionalSetArgs]) -> Optional[str]:
             "$set_once": properties,
             "event": "$set_once",
             "uuid": uuid,
-            "options": _event_options(kwargs.get("options", None)),
+            "options": {
+                **_context_get_context_options(),
+                **_event_options(kwargs.get("options", None)),
+            },
         }
 
         return self._enqueue(msg, disable_geoip)
@@ -2408,7 +2456,14 @@ def _report_capture_failure(
         finally:
             _on_error_state.active = False
 
-    def _enqueue(self, msg, disable_geoip, lane=None, property_allowlist=None):
+    def _enqueue(
+        self,
+        msg,
+        disable_geoip,
+        lane=None,
+        property_allowlist=None,
+        derived_options=None,
+    ):
         # type: (...) -> Optional[str]
         """Push a new `msg` onto a lane's queue (analytics when unspecified), return the event uuid or None."""
 
@@ -2445,7 +2500,15 @@ def _enqueue(self, msg, disable_geoip, lane=None, property_allowlist=None):
             msg["properties"]["$geoip_disable"] = True
 
         if self.super_properties:
-            msg["properties"] = {**msg["properties"], **self.super_properties}
+            msg["properties"] = {**self.super_properties, **msg["properties"]}
+
+        # Each layer overrides the one before it: values the SDK derives, such
+        # as personless, then super options, then context and event options.
+        msg["options"] = {
+            **(derived_options or {}),
+            **_event_options(self.super_options),
+            **(msg.get("options") or {}),
+        }
 
         # Set after the super_properties merge so an explicit `$release_id` from
         # the caller's properties or the super properties wins over the env var.