Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/sdk-compliance.yml
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ jobs:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ matrix.compression }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
env:
HARNESS_IMAGE: ghcr.io/posthog/sdk-test-harness:1.32.0@sha256:7eb6c62e2241ddd48a2dfb326652e7933cd2fe26e0ffcad98cd385d603b4eb82
HARNESS_IMAGE: ghcr.io/posthog/sdk-test-harness:1.34.0@sha256:43f75861fbcf5bc6c3d35511caa2be2d55274054c6071ebeb943aca0bcd0633a
steps:
- name: Check out source code
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
Expand Down
5 changes: 5 additions & 0 deletions .sampo/changesets/known-absent-property-keys.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
posthog: minor
---

Add `person_property_keys_known_absent` and `group_property_keys_known_absent` to flag evaluation. Local evaluation treats a listed key as absent, so `is_not_set` and negated operators match without a `/flags` request, and a listed `$feature_enrollment/<flag key>` means not enrolled. Remote requests send the listed keys. Each list allows at most 1000 keys; a longer list raises `ValueError` and nothing is sent.
72 changes: 71 additions & 1 deletion posthog/__init__.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import datetime # noqa: F401
from typing import Any, Callable, Dict, Mapping, Optional, Union # noqa: F401
from typing import Any, Callable, Dict, Iterable, Mapping, Optional, Union # noqa: F401

from typing_extensions import Unpack

Expand Down Expand Up @@ -847,6 +847,9 @@ def feature_enabled(
send_feature_flag_events: bool = True,
disable_geoip: Optional[bool] = None,
device_id: Optional[str] = None,
*,
person_property_keys_known_absent: Optional[Iterable[str]] = None,
group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None,
) -> Optional[bool]:
"""
Use feature flags to enable or disable features for users.
Expand All @@ -865,6 +868,10 @@ def feature_enabled(
send_feature_flag_events: Whether to send feature flag events
disable_geoip: Whether to disable GeoIP lookup
device_id: Optional device ID override for experience-continuity flags
person_property_keys_known_absent: Person property keys known to be absent.
See ``evaluate_flags``.
group_property_keys_known_absent: Group property keys known to be absent,
keyed by group type. See ``evaluate_flags``.

Details:
You can call `posthog.load_feature_flags()` before to make sure you're not doing unexpected requests.
Expand All @@ -891,6 +898,8 @@ def feature_enabled(
send_feature_flag_events=send_feature_flag_events,
disable_geoip=disable_geoip,
device_id=device_id,
person_property_keys_known_absent=person_property_keys_known_absent,
group_property_keys_known_absent=group_property_keys_known_absent,
)


Expand All @@ -904,6 +913,9 @@ def get_feature_flag(
send_feature_flag_events: bool = True,
disable_geoip: Optional[bool] = None,
device_id: Optional[str] = None,
*,
person_property_keys_known_absent: Optional[Iterable[str]] = None,
group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None,
) -> Optional[FlagValue]:
"""
Get feature flag variant for users. Used with experiments.
Expand All @@ -922,6 +934,10 @@ def get_feature_flag(
send_feature_flag_events: Whether to send feature flag events
disable_geoip: Whether to disable GeoIP lookup
device_id: Optional device ID override for experience-continuity flags
person_property_keys_known_absent: Person property keys known to be absent.
See ``evaluate_flags``.
group_property_keys_known_absent: Group property keys known to be absent,
keyed by group type. See ``evaluate_flags``.

Details:
`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: group_properties={"organization": {"name": "PostHog", "employees": 11}}.
Expand All @@ -948,6 +964,8 @@ def get_feature_flag(
send_feature_flag_events=send_feature_flag_events,
disable_geoip=disable_geoip,
device_id=device_id,
person_property_keys_known_absent=person_property_keys_known_absent,
group_property_keys_known_absent=group_property_keys_known_absent,
)


Expand All @@ -960,6 +978,9 @@ def get_all_flags(
disable_geoip: Optional[bool] = None,
device_id: Optional[str] = None,
flag_keys_to_evaluate: Optional[list[str]] = None,
*,
person_property_keys_known_absent: Optional[Iterable[str]] = None,
group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None,
) -> Optional[dict[str, FlagValue]]:
"""
Get all flags for a given user.
Expand All @@ -973,6 +994,10 @@ def get_all_flags(
disable_geoip: Whether to disable GeoIP lookup
device_id: Optional device ID override for experience-continuity flags
flag_keys_to_evaluate: Optional list of flag keys to evaluate (evaluates all if None)
person_property_keys_known_absent: Person property keys known to be absent.
See ``evaluate_flags``.
group_property_keys_known_absent: Group property keys known to be absent,
keyed by group type. See ``evaluate_flags``.

Details:
Flags are key-value pairs where the key is the flag key and the value is the flag variant, or True, or False.
Expand All @@ -996,6 +1021,8 @@ def get_all_flags(
disable_geoip=disable_geoip,
device_id=device_id,
flag_keys_to_evaluate=flag_keys_to_evaluate,
person_property_keys_known_absent=person_property_keys_known_absent,
group_property_keys_known_absent=group_property_keys_known_absent,
)


Expand All @@ -1009,6 +1036,9 @@ def get_feature_flag_result(
send_feature_flag_events: bool = True,
disable_geoip: Optional[bool] = None,
device_id: Optional[str] = None,
*,
person_property_keys_known_absent: Optional[Iterable[str]] = None,
group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None,
) -> Optional[FeatureFlagResult]:
"""
Get a FeatureFlagResult object which contains the flag result and payload.
Expand All @@ -1030,6 +1060,10 @@ def get_feature_flag_result(
send_feature_flag_events: Whether to send a $feature_flag_called event.
disable_geoip: Whether to disable GeoIP lookup.
device_id: Optional device ID override for experience-continuity flags.
person_property_keys_known_absent: Person property keys known to be absent.
See ``evaluate_flags``.
group_property_keys_known_absent: Group property keys known to be absent,
keyed by group type. See ``evaluate_flags``.

Example:
```python
Expand All @@ -1051,6 +1085,8 @@ def get_feature_flag_result(
send_feature_flag_events=send_feature_flag_events,
disable_geoip=disable_geoip,
device_id=device_id,
person_property_keys_known_absent=person_property_keys_known_absent,
group_property_keys_known_absent=group_property_keys_known_absent,
)


Expand All @@ -1065,6 +1101,9 @@ def get_feature_flag_payload(
send_feature_flag_events: bool = True,
disable_geoip: Optional[bool] = None,
device_id: Optional[str] = None,
*,
person_property_keys_known_absent: Optional[Iterable[str]] = None,
group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None,
) -> Optional[object]:
"""
Get the payload associated with a feature flag value.
Expand All @@ -1083,6 +1122,10 @@ def get_feature_flag_payload(
send_feature_flag_events: Whether to send a $feature_flag_called event.
disable_geoip: Whether to disable GeoIP lookup.
device_id: Optional device ID override for experience-continuity flags.
person_property_keys_known_absent: Person property keys known to be absent.
See ``evaluate_flags``.
group_property_keys_known_absent: Group property keys known to be absent,
keyed by group type. See ``evaluate_flags``.

Returns:
The payload associated with the matched feature flag value, or None.
Expand All @@ -1104,6 +1147,8 @@ def get_feature_flag_payload(
send_feature_flag_events=send_feature_flag_events,
disable_geoip=disable_geoip,
device_id=device_id,
person_property_keys_known_absent=person_property_keys_known_absent,
group_property_keys_known_absent=group_property_keys_known_absent,
)


Expand Down Expand Up @@ -1136,6 +1181,9 @@ def get_all_flags_and_payloads(
disable_geoip: Optional[bool] = None,
device_id: Optional[str] = None,
flag_keys_to_evaluate: Optional[list[str]] = None,
*,
person_property_keys_known_absent: Optional[Iterable[str]] = None,
group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None,
) -> FlagsAndPayloads:
"""
Get all feature flag values and payloads for a user.
Expand All @@ -1150,6 +1198,10 @@ def get_all_flags_and_payloads(
device_id: Optional device ID override for experience-continuity flags.
flag_keys_to_evaluate: Optional list of flag keys to evaluate. Evaluates
all flags when omitted.
person_property_keys_known_absent: Person property keys known to be absent.
See ``evaluate_flags``.
group_property_keys_known_absent: Group property keys known to be absent,
keyed by group type. See ``evaluate_flags``.

Returns:
A dict with ``featureFlags`` and ``featureFlagPayloads`` entries.
Expand All @@ -1167,6 +1219,8 @@ def get_all_flags_and_payloads(
disable_geoip=disable_geoip,
device_id=device_id,
flag_keys_to_evaluate=flag_keys_to_evaluate,
person_property_keys_known_absent=person_property_keys_known_absent,
group_property_keys_known_absent=group_property_keys_known_absent,
)


Expand All @@ -1179,6 +1233,9 @@ def evaluate_flags(
disable_geoip: Optional[bool] = None,
flag_keys: Optional[list[str]] = None,
device_id: Optional[str] = None,
*,
person_property_keys_known_absent: Optional[Iterable[str]] = None,
group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None,
) -> FeatureFlagEvaluations:
"""Evaluate all feature flags for a user in a single call and return a
:class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` /
Expand Down Expand Up @@ -1208,6 +1265,17 @@ def evaluate_flags(
device_id: Optional device ID override. If not provided, falls back to the
context device_id (which may be set via tracing headers). Used by
experience-continuity flags to match users across distinct_id changes.
person_property_keys_known_absent: Person property keys the caller knows are
absent for this person. Local evaluation treats a listed key as absent,
even when ``person_properties`` supplies a value for it: ``is_not_set``
and the negated operators match, and every other operator does not, with
no remote fallback. A listed ``$feature_enrollment/<flag key>`` means not
enrolled. Keys starting with ``__posthog_person_metadata__`` are ignored.
Sent to ``/flags`` on remote evaluation. At most 1000 keys, counting
duplicates; a longer list raises ``ValueError`` and nothing is evaluated.
group_property_keys_known_absent: Group property keys known to be absent,
keyed by group type. A key applies only to its own group type. Same
rules and per-group-type limit as ``person_property_keys_known_absent``.

Examples:
```python
Expand All @@ -1231,6 +1299,8 @@ def evaluate_flags(
disable_geoip=disable_geoip,
flag_keys=flag_keys,
device_id=device_id,
person_property_keys_known_absent=person_property_keys_known_absent,
group_property_keys_known_absent=group_property_keys_known_absent,
)


Expand Down
26 changes: 25 additions & 1 deletion posthog/async_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
import weakref
from dataclasses import replace
from datetime import datetime, timezone
from typing import Any, Callable, Dict, Mapping, Optional, Union
from typing import Any, Callable, Dict, Iterable, Mapping, Optional, Union
from uuid import UUID

from typing_extensions import Unpack
Expand Down Expand Up @@ -94,6 +94,7 @@
)
from .consumer import AI_MAX_MSG_SIZE, MAX_MSG_SIZE
from .emails import AsyncEmails, _client_emails, _validate_options
from .feature_flags import _validate_known_absent_keys
from .feature_flag_evaluations import (
FeatureFlagEvaluations,
_EvaluatedFlagRecord,
Expand Down Expand Up @@ -1117,6 +1118,8 @@ async def _get_flags_decision(
disable_geoip: Optional[bool] = None,
flag_keys: Optional[list[str]] = None,
device_id: Optional[str] = None,
person_property_keys_known_absent: Optional[list[str]] = None,
group_property_keys_known_absent: Optional[dict[str, list[str]]] = None,
):
if disable_geoip is None:
disable_geoip = self.disable_geoip
Expand All @@ -1130,6 +1133,14 @@ async def _get_flags_decision(
}
if flag_keys:
request_data["flag_keys_to_evaluate"] = flag_keys
if person_property_keys_known_absent:
request_data["person_property_keys_known_absent"] = (
person_property_keys_known_absent
)
if group_property_keys_known_absent:
request_data["group_property_keys_known_absent"] = (
group_property_keys_known_absent
)
response = await _async_flags(
self.api_key,
self.host,
Expand All @@ -1155,15 +1166,26 @@ async def evaluate_flags(
disable_geoip: Optional[bool] = None,
flag_keys: Optional[list[str]] = None,
device_id: Optional[str] = None,
person_property_keys_known_absent: Optional[Iterable[str]] = None,
group_property_keys_known_absent: Optional[Mapping[str, Iterable[str]]] = None,
) -> FeatureFlagEvaluations:
"""Evaluate flags remotely without blocking the event loop.

The returned snapshot has synchronous in-memory accessors. Pass it to
``capture(flags=...)`` to attach the exact values used for branching.
This client does not evaluate flags locally, so the snapshot's
``unresolved_flags`` is always empty.

``person_property_keys_known_absent`` and ``group_property_keys_known_absent``
(keyed by group type) list property keys the caller knows are absent. They
are sent to ``/flags``, which treats each listed key as absent even when a
value is supplied for it. Each list holds at most 1000 keys, counting
duplicates; a longer list raises ``ValueError`` and no request is sent.
"""
host = self._get_feature_flag_evaluations_host()
person_keys_known_absent, group_keys_known_absent = _validate_known_absent_keys(
person_property_keys_known_absent, group_property_keys_known_absent
)
if distinct_id is None:
distinct_id = _get_context_distinct_id()
if device_id is None:
Expand Down Expand Up @@ -1207,6 +1229,8 @@ async def evaluate_flags(
disable_geoip=disable_geoip,
flag_keys=flag_keys,
device_id=device_id,
person_property_keys_known_absent=person_keys_known_absent,
group_property_keys_known_absent=group_keys_known_absent,
)
request_id = response.get("requestId")
raw_evaluated_at = response.get("evaluatedAt")
Expand Down
Loading