posthoganalytics 6.7.0__py3-none-any.whl → 7.4.3__py3-none-any.whl

posthoganalytics/contexts.py

@@ -22,6 +22,9 @@ class ContextScope:
         self.session_id: Optional[str] = None
         self.distinct_id: Optional[str] = None
         self.tags: Dict[str, Any] = {}
+        self.capture_exception_code_variables: Optional[bool] = None
+        self.code_variables_mask_patterns: Optional[list] = None
+        self.code_variables_ignore_patterns: Optional[list] = None
 
     def set_session_id(self, session_id: str):
         self.session_id = session_id
@@ -32,6 +35,15 @@ class ContextScope:
     def add_tag(self, key: str, value: Any):
         self.tags[key] = value
 
+    def set_capture_exception_code_variables(self, enabled: bool):
+        self.capture_exception_code_variables = enabled
+
+    def set_code_variables_mask_patterns(self, mask_patterns: list):
+        self.code_variables_mask_patterns = mask_patterns
+
+    def set_code_variables_ignore_patterns(self, ignore_patterns: list):
+        self.code_variables_ignore_patterns = ignore_patterns
+
     def get_parent(self):
         return self.parent
 
@@ -59,6 +71,27 @@ class ContextScope:
             tags.update(new_tags)
         return tags
 
+    def get_capture_exception_code_variables(self) -> Optional[bool]:
+        if self.capture_exception_code_variables is not None:
+            return self.capture_exception_code_variables
+        if self.parent is not None and not self.fresh:
+            return self.parent.get_capture_exception_code_variables()
+        return None
+
+    def get_code_variables_mask_patterns(self) -> Optional[list]:
+        if self.code_variables_mask_patterns is not None:
+            return self.code_variables_mask_patterns
+        if self.parent is not None and not self.fresh:
+            return self.parent.get_code_variables_mask_patterns()
+        return None
+
+    def get_code_variables_ignore_patterns(self) -> Optional[list]:
+        if self.code_variables_ignore_patterns is not None:
+            return self.code_variables_ignore_patterns
+        if self.parent is not None and not self.fresh:
+            return self.parent.get_code_variables_ignore_patterns()
+        return None
+
 
 _context_stack: contextvars.ContextVar[Optional[ContextScope]] = contextvars.ContextVar(
     "posthog_context_stack", default=None
@@ -243,6 +276,54 @@ def get_context_distinct_id() -> Optional[str]:
     return None
 
 
+def set_capture_exception_code_variables_context(enabled: bool) -> None:
+    """
+    Set whether code variables are captured for the current context.
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.set_capture_exception_code_variables(enabled)
+
+
+def set_code_variables_mask_patterns_context(mask_patterns: list) -> None:
+    """
+    Variable names matching these patterns will be masked with *** when capturing code variables.
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.set_code_variables_mask_patterns(mask_patterns)
+
+
+def set_code_variables_ignore_patterns_context(ignore_patterns: list) -> None:
+    """
+    Variable names matching these patterns will be ignored completely when capturing code variables.
+    """
+    current_context = _get_current_context()
+    if current_context:
+        current_context.set_code_variables_ignore_patterns(ignore_patterns)
+
+
+def get_capture_exception_code_variables_context() -> Optional[bool]:
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.get_capture_exception_code_variables()
+    return None
+
+
+def get_code_variables_mask_patterns_context() -> Optional[list]:
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.get_code_variables_mask_patterns()
+    return None
+
+
+def get_code_variables_ignore_patterns_context() -> Optional[list]:
+    current_context = _get_current_context()
+    if current_context:
+        return current_context.get_code_variables_ignore_patterns()
+    return None
+
+
 F = TypeVar("F", bound=Callable[..., Any])
 
 

posthoganalytics/exception_utils.py

@@ -5,6 +5,7 @@
 # 💖open source (under MIT License)
 # We want to keep payloads as similar to Sentry as possible for easy interoperability
 
+import json
 import linecache
 import os
 import re
@@ -13,22 +14,23 @@ import types
 from datetime import datetime
 from types import FrameType, TracebackType  # noqa: F401
 from typing import (  # noqa: F401
+    TYPE_CHECKING,
     Any,
     Dict,
     Iterator,
     List,
     Literal,
     Optional,
+    Pattern,
     Set,
     Tuple,
     TypedDict,
     TypeVar,
     Union,
     cast,
-    TYPE_CHECKING,
 )
 
-from posthoganalytics.args import ExcInfo, ExceptionArg  # noqa: F401
+from posthoganalytics.args import ExceptionArg, ExcInfo  # noqa: F401
 
 try:
     # Python 3.11
@@ -40,6 +42,46 @@ except ImportError:
 
 DEFAULT_MAX_VALUE_LENGTH = 1024
 
+DEFAULT_CODE_VARIABLES_MASK_PATTERNS = [
+    r"(?i).*password.*",
+    r"(?i).*secret.*",
+    r"(?i).*passwd.*",
+    r"(?i).*pwd.*",
+    r"(?i).*api_key.*",
+    r"(?i).*apikey.*",
+    r"(?i).*auth.*",
+    r"(?i).*credentials.*",
+    r"(?i).*privatekey.*",
+    r"(?i).*private_key.*",
+    r"(?i).*token.*",
+    r"(?i).*aws_access_key_id.*",
+    r"(?i).*_pass",
+    r"(?i)sk_.*",
+    r"(?i).*jwt.*",
+]
+
+DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS = [r"^__.*"]
+
+CODE_VARIABLES_REDACTED_VALUE = "$$_posthog_redacted_based_on_masking_rules_$$"
+
+DEFAULT_TOTAL_VARIABLES_SIZE_LIMIT = 20 * 1024
+
+
+class VariableSizeLimiter:
+    def __init__(self, max_size=DEFAULT_TOTAL_VARIABLES_SIZE_LIMIT):
+        self.max_size = max_size
+        self.current_size = 0
+
+    def can_add(self, size):
+        return self.current_size + size <= self.max_size
+
+    def add(self, size):
+        self.current_size += size
+
+    def get_remaining_space(self):
+        return self.max_size - self.current_size
+
+
 LogLevelStr = Literal["fatal", "critical", "error", "warning", "info", "debug"]
 
 Event = TypedDict(
@@ -884,3 +926,209 @@ def strip_string(value, max_length=None):
             "rem": [["!limit", "x", max_length - 3, max_length]],
         },
     )
+
+
+def _compile_patterns(patterns):
+    compiled = []
+    for pattern in patterns:
+        try:
+            compiled.append(re.compile(pattern))
+        except Exception:
+            pass
+    return compiled
+
+
+def _pattern_matches(name, patterns):
+    for pattern in patterns:
+        if pattern.search(name):
+            return True
+    return False
+
+
+def _mask_sensitive_data(value, compiled_mask):
+    if not compiled_mask:
+        return value
+
+    if isinstance(value, dict):
+        result = {}
+        for k, v in value.items():
+            key_str = str(k) if not isinstance(k, str) else k
+            if _pattern_matches(key_str, compiled_mask):
+                result[k] = CODE_VARIABLES_REDACTED_VALUE
+            else:
+                result[k] = _mask_sensitive_data(v, compiled_mask)
+        return result
+    elif isinstance(value, (list, tuple)):
+        masked_items = [_mask_sensitive_data(item, compiled_mask) for item in value]
+        return type(value)(masked_items)
+    elif isinstance(value, str):
+        if _pattern_matches(value, compiled_mask):
+            return CODE_VARIABLES_REDACTED_VALUE
+        return value
+    else:
+        return value
+
+
+def _serialize_variable_value(value, limiter, max_length=1024, compiled_mask=None):
+    try:
+        if value is None:
+            result = "None"
+        elif isinstance(value, bool):
+            result = str(value)
+        elif isinstance(value, (int, float)):
+            result_size = len(str(value))
+            if not limiter.can_add(result_size):
+                return None
+            limiter.add(result_size)
+            return value
+        elif isinstance(value, str):
+            if compiled_mask and _pattern_matches(value, compiled_mask):
+                result = CODE_VARIABLES_REDACTED_VALUE
+            else:
+                result = value
+        else:
+            masked_value = _mask_sensitive_data(value, compiled_mask)
+            result = json.dumps(masked_value)
+
+        if len(result) > max_length:
+            result = result[: max_length - 3] + "..."
+
+        result_size = len(result)
+        if not limiter.can_add(result_size):
+            return None
+        limiter.add(result_size)
+
+        return result
+    except Exception:
+        try:
+            result = repr(value)
+            if len(result) > max_length:
+                result = result[: max_length - 3] + "..."
+
+            result_size = len(result)
+            if not limiter.can_add(result_size):
+                return None
+            limiter.add(result_size)
+            return result
+        except Exception:
+            try:
+                fallback = f"<{type(value).__name__}>"
+                fallback_size = len(fallback)
+                if not limiter.can_add(fallback_size):
+                    return None
+                limiter.add(fallback_size)
+                return fallback
+            except Exception:
+                fallback = "<unserializable object>"
+                fallback_size = len(fallback)
+                if not limiter.can_add(fallback_size):
+                    return None
+                limiter.add(fallback_size)
+                return fallback
+
+
+def _is_simple_type(value):
+    return isinstance(value, (type(None), bool, int, float, str))
+
+
+def serialize_code_variables(
+    frame, limiter, mask_patterns=None, ignore_patterns=None, max_length=1024
+):
+    if mask_patterns is None:
+        mask_patterns = []
+    if ignore_patterns is None:
+        ignore_patterns = []
+
+    compiled_mask = _compile_patterns(mask_patterns)
+    compiled_ignore = _compile_patterns(ignore_patterns)
+
+    try:
+        local_vars = frame.f_locals.copy()
+    except Exception:
+        return {}
+
+    simple_vars = {}
+    complex_vars = {}
+
+    for name, value in local_vars.items():
+        if _pattern_matches(name, compiled_ignore):
+            continue
+
+        if _is_simple_type(value):
+            simple_vars[name] = value
+        else:
+            complex_vars[name] = value
+
+    result = {}
+
+    all_vars = {**simple_vars, **complex_vars}
+    ordered_names = list(sorted(simple_vars.keys())) + list(sorted(complex_vars.keys()))
+
+    for name in ordered_names:
+        value = all_vars[name]
+
+        if _pattern_matches(name, compiled_mask):
+            redacted_value = CODE_VARIABLES_REDACTED_VALUE
+            redacted_size = len(redacted_value)
+            if not limiter.can_add(redacted_size):
+                break
+            limiter.add(redacted_size)
+            result[name] = redacted_value
+        else:
+            serialized = _serialize_variable_value(
+                value, limiter, max_length, compiled_mask
+            )
+            if serialized is None:
+                break
+            result[name] = serialized
+
+    return result
+
+
+def try_attach_code_variables_to_frames(
+    all_exceptions, exc_info, mask_patterns, ignore_patterns
+):
+    try:
+        attach_code_variables_to_frames(
+            all_exceptions, exc_info, mask_patterns, ignore_patterns
+        )
+    except Exception:
+        pass
+
+
+def attach_code_variables_to_frames(
+    all_exceptions, exc_info, mask_patterns, ignore_patterns
+):
+    exc_type, exc_value, traceback = exc_info
+
+    if traceback is None:
+        return
+
+    tb_frames = list(iter_stacks(traceback))
+
+    if not tb_frames:
+        return
+
+    limiter = VariableSizeLimiter()
+
+    for exception in all_exceptions:
+        stacktrace = exception.get("stacktrace")
+        if not stacktrace or "frames" not in stacktrace:
+            continue
+
+        serialized_frames = stacktrace["frames"]
+
+        for serialized_frame, tb_item in zip(serialized_frames, tb_frames):
+            if not serialized_frame.get("in_app"):
+                continue
+
+            variables = serialize_code_variables(
+                tb_item.tb_frame,
+                limiter,
+                mask_patterns=mask_patterns,
+                ignore_patterns=ignore_patterns,
+                max_length=1024,
+            )
+
+            if variables:
+                serialized_frame["code_variables"] = variables

posthoganalytics/feature_flags.py

@@ -22,6 +22,18 @@ class InconclusiveMatchError(Exception):
     pass
 
 
+class RequiresServerEvaluation(Exception):
+    """
+    Raised when feature flag evaluation requires server-side data that is not
+    available locally (e.g., static cohorts, experience continuity).
+
+    This error should propagate immediately to trigger API fallback, unlike
+    InconclusiveMatchError which allows trying other conditions.
+    """
+
+    pass
+
+
 # This function takes a distinct_id and a feature flag key and returns a float between 0 and 1.
 # Given the same distinct_id and key, it'll always return the same float. These floats are
 # uniformly distributed between 0 and 1, so if we want to show this feature to 20% of traffic
@@ -220,14 +232,7 @@ def match_feature_flag_properties(
     ) or []
     valid_variant_keys = [variant["key"] for variant in flag_variants]
 
-    # Stable sort conditions with variant overrides to the top. This ensures that if overrides are present, they are
-    # evaluated first, and the variant override is applied to the first matching condition.
-    sorted_flag_conditions = sorted(
-        flag_conditions,
-        key=lambda condition: 0 if condition.get("variant") else 1,
-    )
-
-    for condition in sorted_flag_conditions:
+    for condition in flag_conditions:
         try:
             # if any one condition resolves to True, we can shortcircuit and return
             # the matching variant
@@ -246,7 +251,12 @@ def match_feature_flag_properties(
                 else:
                     variant = get_matching_variant(flag, distinct_id)
                 return variant or True
+        except RequiresServerEvaluation:
+            # Static cohort or other missing server-side data - must fallback to API
+            raise
         except InconclusiveMatchError:
+            # Evaluation error (bad regex, invalid date, missing property, etc.)
+            # Track that we had an inconclusive match, but try other conditions
             is_inconclusive = True
 
     if is_inconclusive:
@@ -456,8 +466,8 @@ def match_cohort(
     # }
     cohort_id = str(property.get("value"))
     if cohort_id not in cohort_properties:
-        raise InconclusiveMatchError(
-            "can't match cohort without a given cohort property value"
+        raise RequiresServerEvaluation(
+            f"cohort {cohort_id} not found in local cohorts - likely a static cohort that requires server evaluation"
         )
 
     property_group = cohort_properties[cohort_id]
@@ -510,6 +520,9 @@ def match_property_group(
                     # OR group
                     if matches:
                         return True
+            except RequiresServerEvaluation:
+                # Immediately propagate - this condition requires server-side data
+                raise
             except InconclusiveMatchError as e:
                 log.debug(f"Failed to compute property {prop} locally: {e}")
                 error_matching_locally = True
@@ -559,6 +572,9 @@ def match_property_group(
                         return True
                     if not matches and negation:
                         return True
+            except RequiresServerEvaluation:
+                # Immediately propagate - this condition requires server-side data
+                raise
             except InconclusiveMatchError as e:
                 log.debug(f"Failed to compute property {prop} locally: {e}")
                 error_matching_locally = True

posthoganalytics/flag_definition_cache.py

@@ -0,0 +1,127 @@
+"""
+Flag Definition Cache Provider interface for multi-worker environments.
+
+EXPERIMENTAL: This API may change in future minor version bumps.
+
+This module provides an interface for external caching of feature flag definitions,
+enabling multi-worker environments (Kubernetes, load-balanced servers, serverless
+functions) to share flag definitions and reduce API calls.
+
+Usage:
+
+    from posthoganalytics import Posthog
+    from posthoganalytics.flag_definition_cache import FlagDefinitionCacheProvider
+
+    cache = RedisFlagDefinitionCache(redis_client, "my-team")
+    posthog = Posthog(
+        "<project_api_key>",
+        personal_api_key="<personal_api_key>",
+        flag_definition_cache_provider=cache,
+    )
+"""
+
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+from typing_extensions import Required, TypedDict
+
+
+class FlagDefinitionCacheData(TypedDict):
+    """
+    Data structure for cached flag definitions.
+
+    Attributes:
+        flags: List of feature flag definition dictionaries from the API.
+        group_type_mapping: Mapping of group type indices to group names.
+        cohorts: Dictionary of cohort definitions for local evaluation.
+    """
+
+    flags: Required[List[Dict[str, Any]]]
+    group_type_mapping: Required[Dict[str, str]]
+    cohorts: Required[Dict[str, Any]]
+
+
+@runtime_checkable
+class FlagDefinitionCacheProvider(Protocol):
+    """
+    Interface for external caching of feature flag definitions.
+
+    Enables multi-worker environments to share flag definitions, reducing API
+    calls while ensuring all workers have consistent data.
+
+    EXPERIMENTAL: This API may change in future minor version bumps.
+
+    The four methods handle the complete lifecycle of flag definition caching:
+
+    1. `should_fetch_flag_definitions()` - Called before each poll to determine
+       if this worker should fetch new definitions. Use for distributed lock
+       coordination to ensure only one worker fetches at a time.
+
+    2. `get_flag_definitions()` - Called when `should_fetch_flag_definitions()`
+       returns False. Returns cached definitions if available.
+
+    3. `on_flag_definitions_received()` - Called after successfully fetching
+       new definitions from the API. Store the data in your external cache
+       and release any locks.
+
+    4. `shutdown()` - Called when the PostHog client shuts down. Release any
+       distributed locks and clean up resources.
+
+    Error Handling:
+        All methods are wrapped in try/except. Errors will be logged but will
+        never break flag evaluation. On error:
+        - `should_fetch_flag_definitions()` errors default to fetching (fail-safe)
+        - `get_flag_definitions()` errors fall back to API fetch
+        - `on_flag_definitions_received()` errors are logged but flags remain in memory
+        - `shutdown()` errors are logged but shutdown continues
+    """
+
+    def get_flag_definitions(self) -> Optional[FlagDefinitionCacheData]:
+        """
+        Retrieve cached flag definitions.
+
+        Returns:
+            Cached flag definitions if available and valid, None otherwise.
+            Returning None will trigger a fetch from the API if this worker
+            has no flags loaded yet.
+        """
+        ...
+
+    def should_fetch_flag_definitions(self) -> bool:
+        """
+        Determine whether this instance should fetch new flag definitions.
+
+        Use this for distributed lock coordination. Only one worker should
+        return True to avoid thundering herd problems. A typical implementation
+        uses a distributed lock (e.g., Redis SETNX) that expires after the
+        poll interval.
+
+        Returns:
+            True if this instance should fetch from the API, False otherwise.
+            When False, the client will call `get_flag_definitions()` to
+            retrieve cached data instead.
+        """
+        ...
+
+    def on_flag_definitions_received(self, data: FlagDefinitionCacheData) -> None:
+        """
+        Called after successfully receiving new flag definitions from PostHog.
+
+        Use this to store the data in your external cache and release any
+        distributed locks acquired in `should_fetch_flag_definitions()`.
+
+        Args:
+            data: The flag definitions to cache, containing flags,
+                  group_type_mapping, and cohorts.
+        """
+        ...
+
+    def shutdown(self) -> None:
+        """
+        Called when the PostHog client shuts down.
+
+        Use this to release any distributed locks and clean up resources.
+        This method is called even if `should_fetch_flag_definitions()`
+        returned False, so implementations should handle the case where
+        no lock was acquired.
+        """
+        ...