diff --git a/.changeset/quiet-horses-type.md b/.changeset/quiet-horses-type.md new file mode 100644 index 00000000..eeec3932 --- /dev/null +++ b/.changeset/quiet-horses-type.md @@ -0,0 +1,5 @@ +--- +'pypi/posthog': patch +--- + +Improve strict Pyright coverage for public PostHog APIs. diff --git a/.github/scripts/check_strict_types.sh b/.github/scripts/check_strict_types.sh new file mode 100755 index 00000000..d25938fa --- /dev/null +++ b/.github/scripts/check_strict_types.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +set -euo pipefail + +PYTHON_VERSION="${PYTHON_VERSION:-3.11}" +tmp="$(mktemp -d)" +trap 'rm -rf "$tmp"' EXIT + +python -m venv "$tmp/.venv" +"$tmp/.venv/bin/python" -m pip install --quiet --upgrade pip +"$tmp/.venv/bin/python" -m pip install --quiet . pyright + +cat > "$tmp/strict_posthog_types.py" <<'PY' +# pyright: strict +import atexit + +import posthog +from posthog import FeatureFlagEvaluations, FlagValue, Posthog + +client = Posthog("phc_test") +atexit.register(client.shutdown) + +groups: dict[str, str | int] = {"company": 123} + +flag_value: FlagValue | None = client.get_feature_flag("flag", 123, groups=groups) +all_flags: dict[str, FlagValue] | None = posthog.get_all_flags("user", groups=groups) +enabled: bool | None = posthog.feature_enabled("flag", "user", groups=groups) +payload: object | None = client.get_feature_flag_payload("flag", "user", groups=groups) +evaluations: FeatureFlagEvaluations = posthog.evaluate_flags(123, groups=groups) + +_ = (flag_value, all_flags, enabled, payload, evaluations) +PY + +"$tmp/.venv/bin/python" - <<'PY' > "$tmp/public_api_access.py" +import inspect + +import posthog +from posthog import Posthog + +print("# pyright: strict") +print("import posthog") +print("from posthog import Posthog") +print('client = Posthog("phc_test")') + +for name, obj in inspect.getmembers(Posthog): + if name.startswith("_"): + continue + if inspect.isfunction(obj) or inspect.ismethoddescriptor(obj): + print(f"client_{name} = client.{name}") + +for name, obj in inspect.getmembers(posthog): + if name.startswith("_") or name.startswith("inner_"): + continue + if inspect.isfunction(obj): + print(f"module_{name} = posthog.{name}") +PY + +cat > "$tmp/pyrightconfig.json" < Optional[str]: def group_identify( - group_type, # type: str - group_key, # type: str - properties=None, # type: Optional[Dict] - timestamp=None, # type: Optional[datetime.datetime] - uuid=None, # type: Optional[str] - disable_geoip=None, # type: Optional[bool] - distinct_id=None, # type: Optional[str] -): - # type: (...) -> Optional[str] + group_type: str, + group_key: str, + properties: Optional[Dict[str, Any]] = None, + timestamp: Optional[datetime.datetime] = None, + uuid: Optional[str] = None, + disable_geoip: Optional[bool] = None, + distinct_id: Optional[ID_TYPES] = None, +) -> Optional[str]: """ Set properties on a group. @@ -557,13 +562,12 @@ def group_identify( def alias( - previous_id, # type: str - distinct_id, # type: str - timestamp=None, # type: Optional[datetime.datetime] - uuid=None, # type: Optional[str] - disable_geoip=None, # type: Optional[bool] -): - # type: (...) -> Optional[str] + previous_id: str, + distinct_id: str, + timestamp: Optional[datetime.datetime] = None, + uuid: Optional[str] = None, + disable_geoip: Optional[bool] = None, +) -> Optional[str]: """ Associate user behaviour before and after they e.g. register, login, or perform some other identifying action. @@ -629,17 +633,16 @@ def capture_exception( def feature_enabled( - key, # type: str - distinct_id, # type: str - groups=None, # type: Optional[dict] - person_properties=None, # type: Optional[dict] - group_properties=None, # type: Optional[dict] - only_evaluate_locally=False, # type: bool - send_feature_flag_events=True, # type: bool - disable_geoip=None, # type: Optional[bool] - device_id=None, # type: Optional[str] -): - # type: (...) -> bool + key: str, + distinct_id: ID_TYPES, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + send_feature_flag_events: bool = True, + disable_geoip: Optional[bool] = None, + device_id: Optional[str] = None, +) -> Optional[bool]: """ Use feature flags to enable or disable features for users. @@ -683,16 +686,16 @@ def feature_enabled( def get_feature_flag( - key, # type: str - distinct_id, # type: str - groups=None, # type: Optional[dict] - person_properties=None, # type: Optional[dict] - group_properties=None, # type: Optional[dict] - only_evaluate_locally=False, # type: bool - send_feature_flag_events=True, # type: bool - disable_geoip=None, # type: Optional[bool] - device_id=None, # type: Optional[str] -) -> Optional[FeatureFlag]: + key: str, + distinct_id: ID_TYPES, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + send_feature_flag_events: bool = True, + disable_geoip: Optional[bool] = None, + device_id: Optional[str] = None, +) -> Optional[FlagValue]: """ Get feature flag variant for users. Used with experiments. @@ -736,15 +739,15 @@ def get_feature_flag( def get_all_flags( - distinct_id, # type: str - groups=None, # type: Optional[dict] - person_properties=None, # type: Optional[dict] - group_properties=None, # type: Optional[dict] - only_evaluate_locally=False, # type: bool - disable_geoip=None, # type: Optional[bool] - device_id=None, # type: Optional[str] - flag_keys_to_evaluate=None, # type: Optional[list[str]] -) -> Optional[dict[str, FeatureFlag]]: + distinct_id: ID_TYPES, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + disable_geoip: Optional[bool] = None, + device_id: Optional[str] = None, + flag_keys_to_evaluate: Optional[list[str]] = None, +) -> Optional[dict[str, FlagValue]]: """ Get all flags for a given user. @@ -784,17 +787,16 @@ def get_all_flags( def get_feature_flag_result( - key, - distinct_id, - groups=None, # type: Optional[dict] - person_properties=None, # type: Optional[dict] - group_properties=None, # type: Optional[dict] - only_evaluate_locally=False, - send_feature_flag_events=True, - disable_geoip=None, # type: Optional[bool] - device_id=None, # type: Optional[str] -): - # type: (...) -> Optional[FeatureFlagResult] + key: str, + distinct_id: ID_TYPES, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + send_feature_flag_events: bool = True, + disable_geoip: Optional[bool] = None, + device_id: Optional[str] = None, +) -> Optional[FeatureFlagResult]: """ Get a FeatureFlagResult object which contains the flag result and payload. @@ -840,17 +842,17 @@ def get_feature_flag_result( def get_feature_flag_payload( - key, - distinct_id, - match_value=None, - groups=None, # type: Optional[dict] - person_properties=None, # type: Optional[dict] - group_properties=None, # type: Optional[dict] - only_evaluate_locally=False, - send_feature_flag_events=True, - disable_geoip=None, # type: Optional[bool] - device_id=None, # type: Optional[str] -) -> Optional[str]: + key: str, + distinct_id: ID_TYPES, + match_value: Optional[FlagValue] = None, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + send_feature_flag_events: bool = True, + disable_geoip: Optional[bool] = None, + device_id: Optional[str] = None, +) -> Optional[object]: """ Get the payload associated with a feature flag value. @@ -869,6 +871,11 @@ def get_feature_flag_payload( disable_geoip: Whether to disable GeoIP lookup. device_id: Optional device ID override for experience-continuity flags. + Returns: + The payload associated with the matched feature flag value, or None. + This function returns the payload only, not the FeatureFlagResult wrapper + used internally to compute it. + Category: Feature flags """ @@ -888,7 +895,7 @@ def get_feature_flag_payload( def get_remote_config_payload( - key, # type: str + key: str, ): """Get the payload for a remote config feature flag. @@ -908,14 +915,14 @@ def get_remote_config_payload( def get_all_flags_and_payloads( - distinct_id, - groups=None, # type: Optional[dict] - person_properties=None, # type: Optional[dict] - group_properties=None, # type: Optional[dict] - only_evaluate_locally=False, - disable_geoip=None, # type: Optional[bool] - device_id=None, # type: Optional[str] - flag_keys_to_evaluate=None, # type: Optional[list[str]] + distinct_id: ID_TYPES, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + disable_geoip: Optional[bool] = None, + device_id: Optional[str] = None, + flag_keys_to_evaluate: Optional[list[str]] = None, ) -> FlagsAndPayloads: """ Get all feature flag values and payloads for a user. @@ -951,14 +958,14 @@ def get_all_flags_and_payloads( def evaluate_flags( - distinct_id=None, # type: Optional[str] - groups=None, # type: Optional[Dict[str, str]] - person_properties=None, # type: Optional[Dict[str, Any]] - group_properties=None, # type: Optional[Dict[str, Dict[str, Any]]] - only_evaluate_locally=False, # type: bool - disable_geoip=None, # type: Optional[bool] - flag_keys=None, # type: Optional[list] - device_id=None, # type: Optional[str] + distinct_id: Optional[ID_TYPES] = None, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + disable_geoip: Optional[bool] = None, + flag_keys: Optional[list[str]] = None, + device_id: Optional[str] = None, ) -> FeatureFlagEvaluations: """Evaluate all feature flags for a user in a single call and return a :class:`FeatureFlagEvaluations` snapshot. Branch on ``.is_enabled()`` / diff --git a/posthog/client.py b/posthog/client.py index 839e741b..c8627892 100644 --- a/posthog/client.py +++ b/posthog/client.py @@ -9,7 +9,7 @@ import warnings import weakref from datetime import datetime, timedelta, timezone -from typing import Any, Dict, List, Optional, Union +from typing import Any, Dict, List, Mapping, Optional, Union from uuid import UUID, uuid4 from typing_extensions import Unpack @@ -677,11 +677,11 @@ def feature_flags(self, flags): def get_feature_variants( self, - distinct_id, - groups=None, - person_properties=None, - group_properties=None, - disable_geoip=None, + distinct_id: ID_TYPES, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, ) -> dict[str, Union[bool, str]]: @@ -714,11 +714,11 @@ def get_feature_variants( def get_feature_payloads( self, - distinct_id, - groups=None, - person_properties=None, - group_properties=None, - disable_geoip=None, + distinct_id: ID_TYPES, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, ) -> dict[str, str]: @@ -756,11 +756,11 @@ def get_feature_payloads( def get_feature_flags_and_payloads( self, - distinct_id, - groups=None, - person_properties=None, - group_properties=None, - disable_geoip=None, + distinct_id: ID_TYPES, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, ) -> FlagsAndPayloads: @@ -799,10 +799,10 @@ def get_feature_flags_and_payloads( def get_flags_decision( self, distinct_id: Optional[ID_TYPES] = None, - groups: Optional[dict] = None, - person_properties=None, - group_properties=None, - disable_geoip=None, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, ) -> FlagsResponse: @@ -844,10 +844,10 @@ def get_flags_decision( def _get_flags_decision( self, distinct_id: Optional[ID_TYPES] = None, - groups: Optional[dict] = None, - person_properties=None, - group_properties=None, - disable_geoip=None, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, ) -> FlagsResponse: @@ -870,7 +870,7 @@ def _get_flags_decision( if not groups: groups = {} - request_data = { + request_data: Dict[str, Any] = { "distinct_id": distinct_id, "groups": groups, "person_properties": person_properties, @@ -1273,10 +1273,10 @@ def alias( self, previous_id: str, distinct_id: Optional[str], - timestamp=None, - uuid=None, - disable_geoip=None, - ): + timestamp: Optional[Union[datetime, str]] = None, + uuid: Optional[str] = None, + disable_geoip: Optional[bool] = None, + ) -> Optional[str]: """ Create an alias between two distinct IDs. @@ -1304,7 +1304,7 @@ def alias( if personless: return None # Personless alias() does nothing - should this throw? - msg = { + msg: Dict[str, Any] = { "properties": { "distinct_id": previous_id, "alias": distinct_id, @@ -2017,17 +2017,17 @@ def _compute_flag_locally( def feature_enabled( self, - key, - distinct_id, + key: str, + distinct_id: ID_TYPES, *, - groups=None, - person_properties=None, - group_properties=None, - only_evaluate_locally=False, - send_feature_flag_events=True, - disable_geoip=None, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + send_feature_flag_events: bool = True, + disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, - ): + ) -> Optional[bool]: """ Check if a feature flag is enabled for a user. @@ -2100,12 +2100,12 @@ def _get_feature_flag_result( distinct_id: ID_TYPES, *, override_match_value: Optional[FlagValue] = None, - groups: Optional[Dict[str, str]] = None, - person_properties=None, - group_properties=None, - only_evaluate_locally=False, - send_feature_flag_events=True, - disable_geoip=None, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + send_feature_flag_events: bool = True, + disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, ) -> Optional[FeatureFlagResult]: if self.disabled: @@ -2235,15 +2235,15 @@ def _get_feature_flag_result( def get_feature_flag_result( self, - key, - distinct_id, + key: str, + distinct_id: ID_TYPES, *, - groups=None, - person_properties=None, - group_properties=None, - only_evaluate_locally=False, - send_feature_flag_events=True, - disable_geoip=None, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + send_feature_flag_events: bool = True, + disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, ) -> Optional[FeatureFlagResult]: """ @@ -2288,15 +2288,15 @@ def get_feature_flag_result( def get_feature_flag( self, - key, - distinct_id, + key: str, + distinct_id: ID_TYPES, *, - groups=None, - person_properties=None, - group_properties=None, - only_evaluate_locally=False, - send_feature_flag_events=True, - disable_geoip=None, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + send_feature_flag_events: bool = True, + disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, ) -> Optional[FlagValue]: """ @@ -2352,9 +2352,9 @@ def _locally_evaluate_flag( self, key: str, distinct_id: ID_TYPES, - groups: dict[str, str], + groups: Mapping[str, Union[str, int]], person_properties: dict[str, str], - group_properties: dict[str, str], + group_properties: dict[str, dict[str, Any]], device_id: Optional[str] = None, ) -> Optional[FlagValue]: if self.feature_flags is None and self.personal_api_key: @@ -2390,18 +2390,18 @@ def _locally_evaluate_flag( def get_feature_flag_payload( self, - key, - distinct_id, + key: str, + distinct_id: ID_TYPES, *, match_value: Optional[FlagValue] = None, - groups=None, - person_properties=None, - group_properties=None, - only_evaluate_locally=False, - send_feature_flag_events=False, - disable_geoip=None, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + send_feature_flag_events: bool = False, + disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, - ): + ) -> Optional[object]: """ Get the payload for a feature flag. @@ -2417,6 +2417,11 @@ def get_feature_flag_payload( disable_geoip: Whether to disable GeoIP for this request. device_id: The device ID for this request. + Returns: + The payload associated with the matched feature flag value, or None. + This method returns the payload only, not the FeatureFlagResult wrapper + used internally to compute it. + Examples: ```python is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user') @@ -2464,9 +2469,9 @@ def _get_feature_flag_details_from_server( self, key: str, distinct_id: ID_TYPES, - groups: dict[str, str], + groups: Mapping[str, Union[str, int]], person_properties: dict[str, str], - group_properties: dict[str, str], + group_properties: dict[str, dict[str, Any]], disable_geoip: Optional[bool], device_id: Optional[str] = None, ) -> tuple[Optional[FeatureFlag], Optional[str], Optional[int], bool]: @@ -2497,7 +2502,7 @@ def _capture_feature_flag_called( response: Optional[FlagValue], payload: Optional[str], flag_was_locally_evaluated: bool, - groups: Dict[str, str], + groups: Mapping[str, Union[str, int]], disable_geoip: Optional[bool], request_id: Optional[str], evaluated_at: Optional[int], @@ -2546,7 +2551,7 @@ def _capture_feature_flag_called_if_needed( key: str, response: Optional[FlagValue], properties: dict[str, Any], - groups: Optional[Dict[str, str]] = None, + groups: Optional[Mapping[str, Union[str, int]]] = None, disable_geoip: Optional[bool] = None, ) -> None: """Fire a ``$feature_flag_called`` event if the (distinct_id, flag, response, @@ -2643,13 +2648,13 @@ def _compute_payload_locally( def get_all_flags( self, - distinct_id, + distinct_id: ID_TYPES, *, - groups=None, - person_properties=None, - group_properties=None, - only_evaluate_locally=False, - disable_geoip=None, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, ) -> Optional[dict[str, Union[bool, str]]]: @@ -2690,13 +2695,13 @@ def get_all_flags( def get_all_flags_and_payloads( self, - distinct_id, + distinct_id: ID_TYPES, *, - groups=None, - person_properties=None, - group_properties=None, - only_evaluate_locally=False, - disable_geoip=None, + groups: Optional[Mapping[str, Union[str, int]]] = None, + person_properties: Optional[Dict[str, Any]] = None, + group_properties: Optional[Dict[str, Dict[str, Any]]] = None, + only_evaluate_locally: bool = False, + disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None, ) -> FlagsAndPayloads: @@ -2735,6 +2740,8 @@ def get_all_flags_and_payloads( if device_id is None: device_id = get_context_device_id() + groups = groups or {} + response, fallback_to_flags = self._get_all_flags_and_payloads_locally( distinct_id, groups=groups, @@ -2767,7 +2774,7 @@ def evaluate_flags( self, distinct_id: Optional[ID_TYPES] = None, *, - groups: Optional[Dict[str, str]] = None, + groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, @@ -2976,7 +2983,7 @@ def _get_all_flags_and_payloads_locally( self, distinct_id: ID_TYPES, *, - groups: Dict[str, Union[str, int]], + groups: Mapping[str, Union[str, int]], person_properties=None, group_properties=None, warn_on_unknown_groups=False, diff --git a/posthog/feature_flag_evaluations.py b/posthog/feature_flag_evaluations.py index 88bcf916..c2b81537 100644 --- a/posthog/feature_flag_evaluations.py +++ b/posthog/feature_flag_evaluations.py @@ -6,7 +6,7 @@ """ from dataclasses import dataclass -from typing import Any, Callable, Dict, List, Optional, Set +from typing import Any, Callable, Dict, List, Mapping, Optional, Set, Union from posthog.types import FlagValue @@ -62,7 +62,7 @@ def __init__( host: _FeatureFlagEvaluationsHost, distinct_id: str, flags: Dict[str, _EvaluatedFlagRecord], - groups: Optional[Dict[str, str]] = None, + groups: Optional[Mapping[str, Union[str, int]]] = None, disable_geoip: Optional[bool] = None, request_id: Optional[str] = None, evaluated_at: Optional[int] = None, @@ -74,7 +74,7 @@ def __init__( self._host = host self._distinct_id = distinct_id self._flags = flags - self._groups: Dict[str, str] = groups or {} + self._groups: Dict[str, Union[str, int]] = dict(groups or {}) self._disable_geoip = disable_geoip self._request_id = request_id self._evaluated_at = evaluated_at @@ -177,7 +177,7 @@ def _internal_distinct_id(self) -> str: return self._distinct_id @property - def _internal_groups(self) -> Dict[str, str]: + def _internal_groups(self) -> Dict[str, Union[str, int]]: return self._groups def _clone_with( diff --git a/references/public_api_snapshot.txt b/references/public_api_snapshot.txt index f1cd12af..d5512f32 100644 --- a/references/public_api_snapshot.txt +++ b/references/public_api_snapshot.txt @@ -15,7 +15,9 @@ alias posthog.FeatureFlagEvaluations -> posthog.feature_flag_evaluations.Feature alias posthog.FeatureFlagResult -> posthog.types.FeatureFlagResult alias posthog.FlagDefinitionCacheData -> posthog.flag_definition_cache.FlagDefinitionCacheData alias posthog.FlagDefinitionCacheProvider -> posthog.flag_definition_cache.FlagDefinitionCacheProvider +alias posthog.FlagValue -> posthog.types.FlagValue alias posthog.FlagsAndPayloads -> posthog.types.FlagsAndPayloads +alias posthog.ID_TYPES -> posthog.args.ID_TYPES alias posthog.InconclusiveMatchError -> posthog.feature_flags.InconclusiveMatchError alias posthog.OptionalCaptureArgs -> posthog.args.OptionalCaptureArgs alias posthog.OptionalSetArgs -> posthog.args.OptionalSetArgs @@ -758,7 +760,7 @@ class posthog.contexts.ContextScope(parent=None, fresh: bool = False, capture_ex class posthog.exception_capture.ExceptionCapture(client: Client, rate_limiting_enabled=False, bucket_size=DEFAULT_BUCKET_SIZE, refill_rate=DEFAULT_REFILL_RATE, refill_interval_seconds=DEFAULT_REFILL_INTERVAL_SECONDS) class posthog.exception_utils.AnnotatedValue(value, metadata) class posthog.exception_utils.VariableSizeLimiter(max_size=DEFAULT_TOTAL_VARIABLES_SIZE_LIMIT) -class posthog.feature_flag_evaluations.FeatureFlagEvaluations(host: _FeatureFlagEvaluationsHost, distinct_id: str, flags: Dict[str, _EvaluatedFlagRecord], groups: Optional[Dict[str, str]] = None, disable_geoip: Optional[bool] = None, request_id: Optional[str] = None, evaluated_at: Optional[int] = None, errors_while_computing: bool = False, quota_limited: bool = False, accessed: Optional[Set[str]] = None) +class posthog.feature_flag_evaluations.FeatureFlagEvaluations(host: _FeatureFlagEvaluationsHost, distinct_id: str, flags: Dict[str, _EvaluatedFlagRecord], groups: Optional[Mapping[str, Union[str, int]]] = None, disable_geoip: Optional[bool] = None, request_id: Optional[str] = None, evaluated_at: Optional[int] = None, errors_while_computing: bool = False, quota_limited: bool = False, accessed: Optional[Set[str]] = None) class posthog.feature_flags.ConditionMatch class posthog.feature_flags.InconclusiveMatchError class posthog.feature_flags.RequiresServerEvaluation @@ -863,7 +865,7 @@ function posthog.ai.utils.merge_usage_stats(target: TokenUsage, source: TokenUsa function posthog.ai.utils.sanitize_messages(data: Any, provider: str) -> Any function posthog.ai.utils.serialize_raw_usage(raw_usage: Any) -> Optional[Dict[str, Any]] function posthog.ai.utils.with_privacy_mode(ph_client: PostHogClient, privacy_mode: bool, value: Any) -function posthog.alias(previous_id, distinct_id, timestamp=None, uuid=None, disable_geoip=None) +function posthog.alias(previous_id: str, distinct_id: str, timestamp: Optional[datetime.datetime] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None) -> Optional[str] function posthog.capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] function posthog.capture_exception(exception: Optional[ExceptionArg] = None, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] function posthog.client.add_context_tags(properties) @@ -888,7 +890,7 @@ function posthog.contexts.set_code_variables_mask_url_credentials_context(enable function posthog.contexts.set_context_device_id(device_id: str) -> None function posthog.contexts.set_context_session(session_id: str) -> None function posthog.contexts.tag(key: str, value: Any) -> None -function posthog.evaluate_flags(distinct_id=None, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, disable_geoip=None, flag_keys=None, device_id=None) -> FeatureFlagEvaluations +function posthog.evaluate_flags(distinct_id: Optional[ID_TYPES] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys: Optional[list[str]] = None, device_id: Optional[str] = None) -> FeatureFlagEvaluations function posthog.exception_utils.attach_code_variables_to_frames(all_exceptions, exc_info, mask_patterns, ignore_patterns, mask_url_credentials=True) function posthog.exception_utils.construct_artificial_traceback(e) function posthog.exception_utils.event_hint_with_exc_info(exc_info=None) @@ -921,7 +923,7 @@ function posthog.exception_utils.to_string(value) function posthog.exception_utils.to_timestamp(value) function posthog.exception_utils.try_attach_code_variables_to_frames(all_exceptions, exc_info, mask_patterns, ignore_patterns, mask_url_credentials=True) function posthog.exception_utils.walk_exception_chain(exc_info) -function posthog.feature_enabled(key, distinct_id, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, send_feature_flag_events=True, disable_geoip=None, device_id=None) +function posthog.feature_enabled(key: str, distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[bool] function posthog.feature_flag_definitions() function posthog.feature_flags.evaluate_flag_dependency(property, flags_by_key, evaluation_cache, distinct_id, properties, cohort_properties, device_id=None) function posthog.feature_flags.get_matching_variant(flag, bucketing_value) @@ -937,14 +939,14 @@ function posthog.feature_flags.relative_date_parse_for_feature_flag_matching(val function posthog.feature_flags.resolve_bucketing_value(flag, distinct_id, device_id=None) function posthog.feature_flags.variant_lookup_table(feature_flag) function posthog.flush(timeout_seconds: Optional[float] = 10) -> None -function posthog.get_all_flags(distinct_id, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, disable_geoip=None, device_id=None, flag_keys_to_evaluate=None) -> Optional[dict[str, FeatureFlag]] -function posthog.get_all_flags_and_payloads(distinct_id, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, disable_geoip=None, device_id=None, flag_keys_to_evaluate=None) -> FlagsAndPayloads -function posthog.get_feature_flag(key, distinct_id, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, send_feature_flag_events=True, disable_geoip=None, device_id=None) -> Optional[FeatureFlag] -function posthog.get_feature_flag_payload(key, distinct_id, match_value=None, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, send_feature_flag_events=True, disable_geoip=None, device_id=None) -> Optional[str] -function posthog.get_feature_flag_result(key, distinct_id, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, send_feature_flag_events=True, disable_geoip=None, device_id=None) -function posthog.get_remote_config_payload(key) +function posthog.get_all_flags(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, flag_keys_to_evaluate: Optional[list[str]] = None) -> Optional[dict[str, FlagValue]] +function posthog.get_all_flags_and_payloads(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None, flag_keys_to_evaluate: Optional[list[str]] = None) -> FlagsAndPayloads +function posthog.get_feature_flag(key: str, distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[FlagValue] +function posthog.get_feature_flag_payload(key: str, distinct_id: ID_TYPES, match_value: Optional[FlagValue] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[object] +function posthog.get_feature_flag_result(key: str, distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[FeatureFlagResult] +function posthog.get_remote_config_payload(key: str) function posthog.get_tags() -> Dict[str, Any] -function posthog.group_identify(group_type, group_key, properties=None, timestamp=None, uuid=None, disable_geoip=None, distinct_id=None) +function posthog.group_identify(group_type: str, group_key: str, properties: Optional[Dict[str, Any]] = None, timestamp: Optional[datetime.datetime] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None) -> Optional[str] function posthog.identify_context(distinct_id: str) function posthog.integrations.django.markcoroutinefunction(func) function posthog.join() -> None @@ -965,8 +967,8 @@ function posthog.request.set_socket_options(socket_options: Optional[SocketOptio function posthog.scoped(fresh=False, capture_exceptions: Optional[bool] = None) function posthog.set(**kwargs: Unpack[OptionalSetArgs]) -> Optional[str] function posthog.set_capture_exception_code_variables_context(enabled: bool) -function posthog.set_code_variables_ignore_patterns_context(ignore_patterns: list) -function posthog.set_code_variables_mask_patterns_context(mask_patterns: list) +function posthog.set_code_variables_ignore_patterns_context(ignore_patterns: list[str]) +function posthog.set_code_variables_mask_patterns_context(mask_patterns: list[str]) function posthog.set_code_variables_mask_url_credentials_context(enabled: bool) function posthog.set_context_device_id(device_id: str) function posthog.set_context_session(session_id: str) @@ -1053,22 +1055,22 @@ method posthog.ai.prompts.Prompts.compile(prompt: str, variables: PromptVariable method posthog.ai.prompts.Prompts.get(name: str, *, with_metadata: Optional[bool] = None, cache_ttl_seconds: Optional[int] = None, fallback: Optional[str] = None, version: Optional[int] = None) -> Union[str, PromptResult] method posthog.bucketed_rate_limiter.BucketedRateLimiter.consume_rate_limit(key: Hashable) -> bool method posthog.bucketed_rate_limiter.BucketedRateLimiter.stop() -> None -method posthog.client.Client.alias(previous_id: str, distinct_id: Optional[str], timestamp=None, uuid=None, disable_geoip=None) +method posthog.client.Client.alias(previous_id: str, distinct_id: Optional[str], timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None) -> Optional[str] method posthog.client.Client.capture(event: str, **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] method posthog.client.Client.capture_exception(exception: Optional[ExceptionArg], **kwargs: Unpack[OptionalCaptureArgs]) -> Optional[str] -method posthog.client.Client.evaluate_flags(distinct_id: Optional[ID_TYPES] = None, *, groups: Optional[Dict[str, str]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys: Optional[List[str]] = None, device_id: Optional[str] = None) -> FeatureFlagEvaluations -method posthog.client.Client.feature_enabled(key, distinct_id, *, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, send_feature_flag_events=True, disable_geoip=None, device_id: Optional[str] = None) +method posthog.client.Client.evaluate_flags(distinct_id: Optional[ID_TYPES] = None, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys: Optional[List[str]] = None, device_id: Optional[str] = None) -> FeatureFlagEvaluations +method posthog.client.Client.feature_enabled(key: str, distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[bool] method posthog.client.Client.feature_flag_definitions() method posthog.client.Client.flush(timeout_seconds: Optional[float] = 10) -> None -method posthog.client.Client.get_all_flags(distinct_id, *, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, disable_geoip=None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> Optional[dict[str, Union[bool, str]]] -method posthog.client.Client.get_all_flags_and_payloads(distinct_id, *, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, disable_geoip=None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> FlagsAndPayloads -method posthog.client.Client.get_feature_flag(key, distinct_id, *, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, send_feature_flag_events=True, disable_geoip=None, device_id: Optional[str] = None) -> Optional[FlagValue] -method posthog.client.Client.get_feature_flag_payload(key, distinct_id, *, match_value: Optional[FlagValue] = None, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, send_feature_flag_events=False, disable_geoip=None, device_id: Optional[str] = None) -method posthog.client.Client.get_feature_flag_result(key, distinct_id, *, groups=None, person_properties=None, group_properties=None, only_evaluate_locally=False, send_feature_flag_events=True, disable_geoip=None, device_id: Optional[str] = None) -> Optional[FeatureFlagResult] -method posthog.client.Client.get_feature_flags_and_payloads(distinct_id, groups=None, person_properties=None, group_properties=None, disable_geoip=None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> FlagsAndPayloads -method posthog.client.Client.get_feature_payloads(distinct_id, groups=None, person_properties=None, group_properties=None, disable_geoip=None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> dict[str, str] -method posthog.client.Client.get_feature_variants(distinct_id, groups=None, person_properties=None, group_properties=None, disable_geoip=None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> dict[str, Union[bool, str]] -method posthog.client.Client.get_flags_decision(distinct_id: Optional[ID_TYPES] = None, groups: Optional[dict] = None, person_properties=None, group_properties=None, disable_geoip=None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> FlagsResponse +method posthog.client.Client.get_all_flags(distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> Optional[dict[str, Union[bool, str]]] +method posthog.client.Client.get_all_flags_and_payloads(distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> FlagsAndPayloads +method posthog.client.Client.get_feature_flag(key: str, distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[FlagValue] +method posthog.client.Client.get_feature_flag_payload(key: str, distinct_id: ID_TYPES, *, match_value: Optional[FlagValue] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = False, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[object] +method posthog.client.Client.get_feature_flag_result(key: str, distinct_id: ID_TYPES, *, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, only_evaluate_locally: bool = False, send_feature_flag_events: bool = True, disable_geoip: Optional[bool] = None, device_id: Optional[str] = None) -> Optional[FeatureFlagResult] +method posthog.client.Client.get_feature_flags_and_payloads(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> FlagsAndPayloads +method posthog.client.Client.get_feature_payloads(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> dict[str, str] +method posthog.client.Client.get_feature_variants(distinct_id: ID_TYPES, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> dict[str, Union[bool, str]] +method posthog.client.Client.get_flags_decision(distinct_id: Optional[ID_TYPES] = None, groups: Optional[Mapping[str, Union[str, int]]] = None, person_properties: Optional[Dict[str, Any]] = None, group_properties: Optional[Dict[str, Dict[str, Any]]] = None, disable_geoip: Optional[bool] = None, flag_keys_to_evaluate: Optional[list[str]] = None, device_id: Optional[str] = None) -> FlagsResponse method posthog.client.Client.get_remote_config_payload(key: str) method posthog.client.Client.get_tags() -> Dict[str, Any] method posthog.client.Client.group_identify(group_type: str, group_key: str, properties: Optional[Dict[str, Any]] = None, timestamp: Optional[Union[datetime, str]] = None, uuid: Optional[Union[str, UUID]] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None) -> Optional[str]