fix: treat a per-call disable_geoip as a value of the event

A disable_geoip argument now fills $geoip_disable as the event's own
value: above context tags, super_properties and the client setting, and
below a $geoip_disable in the call's properties. disable_geoip=False now
sends $geoip_disable: false. Client and AsyncClient share the layer in
_build_event_defaults.

Author: eli-r-ph

.sampo/changesets/call-disable-geoip-event-value.md

@@ -0,0 +1,5 @@
+---
+pypi/posthog: major
+---
+
+A `disable_geoip` argument to a call now counts as a value of that event. It wins over a `$geoip_disable` in context tags or `super_properties`, and a `$geoip_disable` in the call's own `properties` still wins over it. `disable_geoip=False` now sends `$geoip_disable: false`, so it turns GeoIP lookup on for that event even when a context tag or `super_properties` turns it off. The client's `disable_geoip` setting keeps its place below every caller value. `AsyncPosthog` follows the same rules.

docs/migration-7.x-to-8.0.md

@@ -149,10 +149,10 @@ Capture v1 sends processing options in an `options` object, next to `properties`
 
 Values apply in this order. Steps 2 to 4 fill only the options and properties that the steps before them left unset:
 
-1. the `options` and `properties` of the call
+1. the `options` and `properties` of the call, then the call's `disable_geoip` argument, which fills `$geoip_disable`
 2. context options and tags
 3. `super_options` and `super_properties`
-4. values the SDK sets: `$is_server` from `is_server`, `$geoip_disable` from `disable_geoip`, system properties such as `$os` and `$python_version`, `options.process_person_profile = false` for events without a distinct ID, and `$release_id` from `POSTHOG_RELEASE_ID`
+4. values the SDK sets: `$is_server` from `is_server`, `$geoip_disable` from the client's `disable_geoip` setting, system properties such as `$os` and `$python_version`, `options.process_person_profile = false` for events without a distinct ID, and `$release_id` from `POSTHOG_RELEASE_ID`
 5. `before_send`, which sees the result of steps 1 to 4 and can change or remove any of it
 6. legacy properties, which fill unset options and are then removed
 
@@ -165,6 +165,7 @@ These changes follow from this order:
 
 - Properties passed to a call now override `super_properties`. `super_properties` can no longer change `$lib` or `$lib_version`.
 - A `$is_server`, `$geoip_disable` or system property such as `$os` that you set in a call or a context tag now wins over the SDK's value. In 7.x the SDK overwrote it. `super_properties` win over the SDK's value too, so `super_properties={"$geoip_disable": False}` turns GeoIP lookup on for events, even with `disable_geoip=True`.
+- A `disable_geoip` argument to a call belongs to that event, so it wins over context tags and `super_properties`. A `$geoip_disable` in the call's own `properties` still wins over it. `disable_geoip=False` now sends `$geoip_disable: false`. In 7.x it sent no `$geoip_disable` property.
 - The `groups` argument merges into a `$groups` property of the call, and wins key by key. In 7.x it replaced the property. MCP events merge their identity's groups into a custom `$groups` property the same way.
 - A `$set`, `$set_once`, `$groups` or `$group_set` in `super_properties` no longer replaces the whole value of the call. The two merge, and the call wins key by key.
 - An event without a distinct ID gets `options.process_person_profile = false`. A `$process_person_profile: true` property no longer turns person processing back on. Set the option instead.

posthog/async_client.py

@@ -521,8 +521,6 @@ def _event_defaults(
         disable_geoip: Optional[bool] = None,
         system_properties: Optional[dict[str, Any]] = None,
     ) -> _EventDefaults:
-        if disable_geoip is None:
-            disable_geoip = self.disable_geoip
         return _build_event_defaults(
             super_properties=self.super_properties,
             super_options=self.super_options,
@@ -532,7 +530,8 @@ def _event_defaults(
             derived_options=derived_options,
             property_allowlist=property_allowlist,
             is_server=self.is_server,
-            disable_geoip=disable_geoip,
+            disable_geoip=self.disable_geoip,
+            call_disable_geoip=disable_geoip,
             system_properties=system_properties,
         )
 

posthog/capture_event.py

@@ -124,7 +124,7 @@ def _event_options(value: Any) -> dict[str, Any]:
 
 @dataclass(frozen=True)
 class _EventDefaults:
-    """Context, global and SDK-derived values for one event, highest layer first.
+    """Per-call, context, global and SDK-derived values for one event, highest layer first.
 
     They fill in before ``before_send``, so the hook sees them and can change
     or remove them. The event's own values win over every default.
@@ -146,9 +146,18 @@ def _build_event_defaults(
     property_allowlist: Optional[Collection[str]] = None,
     is_server: bool = False,
     disable_geoip: bool = False,
+    call_disable_geoip: Optional[bool] = None,
     system_properties: Optional[Mapping[str, Any]] = None,
 ) -> _EventDefaults:
-    """Order the layers: context, then global, then values the SDK derives."""
+    """Order the layers: per-call arguments, context, global, then SDK values.
+
+    ``disable_geoip`` is the client setting, an SDK value. ``call_disable_geoip``
+    is the argument of one call: it is a value of that event, so only the
+    event's own ``$geoip_disable`` property beats it.
+    """
+    call_properties = (
+        {} if call_disable_geoip is None else {"$geoip_disable": call_disable_geoip}
+    )
     # A value in the event, the context or super properties wins over every
     # value the SDK adds, including `$is_server` and `$geoip_disable`.
     sdk_properties = dict(system_properties or {})
@@ -160,6 +169,7 @@ def _build_event_defaults(
         sdk_properties["$geoip_disable"] = True
     return _EventDefaults(
         property_layers=(
+            call_properties,
             context_properties or {},
             super_properties or {},
             sdk_properties,

posthog/client.py

@@ -1682,9 +1682,10 @@ def capture(
             send_feature_flags: Deprecated. Prefer flags=... from
                 evaluate_flags(). When truthy, evaluates flags during capture and
                 attaches them to the event.
-            disable_geoip: Whether to disable GeoIP for this event. A
-                ``$geoip_disable`` property in the event, context tags or
-                ``super_properties`` wins.
+            disable_geoip: Whether to disable GeoIP for this event. It wins
+                over a ``$geoip_disable`` in context tags or
+                ``super_properties``. A ``$geoip_disable`` property in this
+                call's ``properties`` wins over it.
             options: Capture options for this event, such as
                 ``{"process_person_profile": False}``. Sent as given, for
                 PostHog to validate. They override context options and
@@ -2527,9 +2528,6 @@ def _enqueue(
         msg["properties"]["$lib"] = self._library_id
         msg["properties"]["$lib_version"] = self._library_version
 
-        if disable_geoip is None:
-            disable_geoip = self.disable_geoip
-
         msg["options"] = msg.get("options") or {}
 
         _fill_event_defaults(
@@ -2543,7 +2541,8 @@ def _enqueue(
                 derived_options=derived_options,
                 property_allowlist=property_allowlist,
                 is_server=self.is_server,
-                disable_geoip=disable_geoip,
+                disable_geoip=self.disable_geoip,
+                call_disable_geoip=disable_geoip,
                 system_properties=system_properties,
             ),
         )

posthog/test/test_client.py

@@ -1364,7 +1364,7 @@ def test_basic_capture_with_feature_flags_and_disable_geoip_returns_correctly(
             self.assertEqual(msg["event"], "python test event")
             self.assertTrue(isinstance(msg["timestamp"], str))
             self.assertIsNotNone(msg.get("uuid"))
-            self.assertTrue("$geoip_disable" not in msg["properties"])
+            self.assertIs(msg["properties"]["$geoip_disable"], False)
             self.assertEqual(msg["distinct_id"], "distinct_id")
             self.assertEqual(msg["properties"]["$lib"], "posthog-python")
             self.assertEqual(msg["properties"]["$lib_version"], VERSION)
@@ -3800,7 +3800,7 @@ def test_disable_geoip_override_on_events(self):
             # Check page event
             page_batch = sent_batch(mock_post, 1)
             identify_msg = page_batch[0]
-            self.assertEqual("$geoip_disable" not in identify_msg["properties"], True)
+            self.assertIs(identify_msg["properties"]["$geoip_disable"], False)
 
     def test_disable_geoip_method_overrides_init_on_events(self):
         with patch_capture_send("client") as mock_post:
@@ -3819,7 +3819,7 @@ def test_disable_geoip_method_overrides_init_on_events(self):
             mock_post.assert_called_once()
             batch_data = sent_batch(mock_post)
             msg = batch_data[0]
-            self.assertTrue("$geoip_disable" not in msg["properties"])
+            self.assertIs(msg["properties"]["$geoip_disable"], False)
 
     @mock.patch("posthog.client.flags")
     def test_disable_geoip_default_on_decide(self, patch_flags):

posthog/test/test_event_options.py

@@ -410,6 +410,59 @@ async def test_async_caller_values_beat_sdk_values(source):
     _assert_caller_values(events, CALLER_SDK_VALUES)
 
 
+GEOIP_CALL_CASES = [
+    pytest.param(True, "context", False, True, id="call_beats_context"),
+    pytest.param(True, "super", False, True, id="call_beats_super"),
+    pytest.param(False, "super", True, False, id="call_false_beats_super"),
+    pytest.param(False, None, None, False, id="call_false_beats_client_setting"),
+    pytest.param(True, "event", False, False, id="event_property_beats_call"),
+]
+
+
+def _capture_with_call_geoip(call_value, source, layer_value):
+    def call(client):
+        with new_context(fresh=True):
+            if source == "context":
+                tag("$geoip_disable", layer_value)
+            properties = {"$geoip_disable": layer_value} if source == "event" else None
+            return client.capture(
+                "e", distinct_id="u", properties=properties, disable_geoip=call_value
+            )
+
+    return call
+
+
+def _geoip_layer_config(source, layer_value):
+    if source == "super":
+        return {"super_properties": {"$geoip_disable": layer_value}}
+    return {}
+
+
+@pytest.mark.parametrize("call_value, source, layer_value, expected", GEOIP_CALL_CASES)
+def test_sync_call_disable_geoip_is_an_event_value(
+    call_value, source, layer_value, expected
+):
+    events = _sync_wire_events(
+        _capture_with_call_geoip(call_value, source, layer_value),
+        disable_geoip=True,
+        **_geoip_layer_config(source, layer_value),
+    )
+    assert events[0]["properties"]["$geoip_disable"] is expected
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("call_value, source, layer_value, expected", GEOIP_CALL_CASES)
+async def test_async_call_disable_geoip_is_an_event_value(
+    call_value, source, layer_value, expected
+):
+    events = await _async_wire_events(
+        _capture_with_call_geoip(call_value, source, layer_value),
+        disable_geoip=True,
+        **_geoip_layer_config(source, layer_value),
+    )
+    assert events[0]["properties"]["$geoip_disable"] is expected
+
+
 @pytest.mark.parametrize("method", list(CAPTURE_CALLS))
 def test_sync_super_properties_beat_sdk_values_on_every_path(method):
     events = _sync_wire_events(