featureflip 2.3.0__tar.gz → 2.4.0__tar.gz

{featureflip-2.3.0 → featureflip-2.4.0}/CHANGELOG.md

@@ -1,16 +1,51 @@
 # Changelog
 
-## Unreleased
+## 2.4.0 — 2026-07-29
 
 ### Added
 
-- **Semantic-version condition operators.** Five new operators — `SemverEquals`, `SemverGreaterThan`, `SemverGreaterThanOrEqual`, `SemverLessThan`, `SemverLessThanOrEqual` — compare an attribute against the condition value(s) as a semantic version (https://semver.org) rather than a decimal, so `2.10.1` correctly satisfies `>= 2.0` (the numeric path mis-parsed multi-segment versions). Tolerant of a leading `v`, `+build` metadata, missing trailing segments (`2.0` == `2.0.0`), and `-prerelease` precedence; unparseable versions match nothing. A rule matches when any supplied condition value satisfies the operator, mirroring the numeric/date operators and the evaluation engine. New module: `featureflip/_semver.py`.
+- **`onEvaluation` inspector callback.** `inspectors` config option registering in-process observers fired on every evaluation, receiving flag key, context, value, variation key, reason, rule id and prerequisite key. Also threaded through `FeatureflipClient.for_testing(flags, inspectors=...)`, which bypasses `__init__` (#1914).
 
-- **Prerequisite flag support.** Flags can declare other flags as prerequisites; the flag's rules and fallthrough only run when every prerequisite serves the expected variation, otherwise the off variation is served with `EvaluationReason.PREREQUISITE_FAILED` and `prerequisite_key` set on the `EvaluationDetail`. Resolution is recursive (depth-capped at 10) with per-call memoisation. New types: `Prerequisite`, `EvaluationReason.PREREQUISITE_FAILED`. New `EvaluationDetail` fields: `variation_key`, `prerequisite_key`. New batch-eval entry point: `FlagEvaluator.evaluate_with_shared_memo(...)`.
+### Fixed
+
+- A served variation key the flag does not define now reports reason `ERROR` with the caller's default, instead of a misleading success reason (#1989).
+
+## 2.3.1 — 2026-07-14
+
+### Fixed
+
+- Analytics events are sent in the backend's `SdkEventDto` wire shape (#1920).
+
+## 2.3.0 — 2026-07-13
+
+### Fixed
+
+- Outage-recovery hardening: polling fallback, reconnect backoff, and SSE `sync` applied as a full store replace (#1868, #1896).
+- The streaming fallback poller is reaped once the stream is healthy, instead of continuing to poll alongside it (#1895).
+
+## 2.2.0 — 2026-06-19
+
+### Added
+
+- **Semantic-version condition operators.** Five new operators — `SemverEquals`, `SemverGreaterThan`, `SemverGreaterThanOrEqual`, `SemverLessThan`, `SemverLessThanOrEqual` — compare an attribute against the condition value(s) as a semantic version (https://semver.org) rather than a decimal, so `2.10.1` correctly satisfies `>= 2.0` (the numeric path mis-parsed multi-segment versions). Tolerant of a leading `v`, `+build` metadata, missing trailing segments (`2.0` == `2.0.0`), and `-prerelease` precedence; unparseable versions match nothing. A rule matches when any supplied condition value satisfies the operator, mirroring the numeric/date operators and the evaluation engine. New module: `featureflip/_semver.py` (#1409).
 
 ### Fixed
 
-- **Multi-word condition operators sent by the server now parse correctly.** The evaluation API serializes operators in PascalCase (e.g. `GreaterThan`, `SemverGreaterThanOrEqual`); operator parsing previously lower-cased the wire string, which collapsed the word boundaries (`GreaterThan` → `greaterthan`) and failed to resolve any multi-word operator. `ConditionOperator` now normalizes PascalCase → snake_case via `_missing_`.
+- **Multi-word condition operators sent by the server now parse correctly.** The evaluation API serializes operators in PascalCase (e.g. `GreaterThan`, `SemverGreaterThanOrEqual`); operator parsing previously lower-cased the wire string, which collapsed the word boundaries (`GreaterThan` → `greaterthan`) and failed to resolve any multi-word operator. `ConditionOperator` now normalizes PascalCase → snake_case via `_missing_` (#1429).
+- Relational operators match if the attribute satisfies the operator against **any** supplied condition value (#1443).
+- `MatchesRegex` and semver prerelease comparison are now case-sensitive, matching the engine (#1453, #1454).
+- `Before`/`After` date operators aligned with the engine (#1455).
+- Type-aware numeric coercion for `Equals`/`In` (#1458).
+- Keyless rollouts serve the control variation deterministically (#1457).
+- Segment-keyed rules with no segment source fail closed (#1459).
+- Present-but-null attributes are treated as absent (#1460).
+- Environment-level percentage rollouts with no variations no longer throw (#1469).
+
+## 2.1.0 — 2026-05-27
+
+### Added
+
+- **Prerequisite flag support.** Flags can declare other flags as prerequisites; the flag's rules and fallthrough only run when every prerequisite serves the expected variation, otherwise the off variation is served with `EvaluationReason.PREREQUISITE_FAILED` and `prerequisite_key` set on the `EvaluationDetail`. Resolution is recursive (depth-capped at 10) with per-call memoisation. New types: `Prerequisite`, `EvaluationReason.PREREQUISITE_FAILED`. New `EvaluationDetail` fields: `variation_key`, `prerequisite_key`. New batch-eval entry point: `FlagEvaluator.evaluate_with_shared_memo(...)` (#1108).
 
 ## 2.0.0 — 2026-04-08
 

{featureflip-2.3.0 → featureflip-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: featureflip
-Version: 2.3.0
+Version: 2.4.0
 Summary: Python SDK for Featureflip - a feature flag SaaS platform
 Project-URL: Homepage, https://featureflip.io
 Project-URL: Documentation, https://featureflip.io/docs/sdks/python/

{featureflip-2.3.0 → featureflip-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "featureflip"
-version = "2.3.0"
+version = "2.4.0"
 description = "Python SDK for Featureflip - a feature flag SaaS platform"
 readme = "README.md"
 license = "Apache-2.0"

{featureflip-2.3.0 → featureflip-2.4.0}/src/featureflip/__init__.py

@@ -11,6 +11,7 @@ from featureflip.exceptions import (
     FeatureflipError,
     InitializationError,
 )
+from featureflip.inspector import EvaluationEvent, EvaluationInspector
 from featureflip.models import (
     Condition,
     ConditionGroup,
@@ -36,6 +37,8 @@ __all__: list[str] = [
     "ConfigurationError",
     "EvaluationContext",
     "EvaluationDetail",
+    "EvaluationEvent",
+    "EvaluationInspector",
     "EvaluationReason",
     "FeatureflipClient",
     "FeatureflipError",

{featureflip-2.3.0 → featureflip-2.4.0}/src/featureflip/_core.py

@@ -28,8 +28,10 @@ from featureflip.context import EvaluationContext
 from featureflip.detail import EvaluationDetail, EvaluationReason
 from featureflip.evaluation import FlagEvaluator
 from featureflip.exceptions import InitializationError
+from featureflip.inspector import EvaluationEvent
 
 if TYPE_CHECKING:
+    from featureflip.inspector import EvaluationInspector
     from featureflip.models import FlagConfiguration, Segment
 
 logger = structlog.get_logger()
@@ -37,6 +39,19 @@ logger = structlog.get_logger()
 T = TypeVar("T")
 
 
+def _resolve_user_id(context: dict[str, Any]) -> str | None:
+    """Resolve the built-in user id from a raw context dict.
+
+    Honors the ``user_id`` / ``userId`` alias (universal across the engine and
+    every SDK) so a caller passing either spelling gets the same top-level
+    ``userId`` on analytics events. Returns ``None`` when neither is present.
+    """
+    raw = context.get("user_id")
+    if raw is None:
+        raw = context.get("userId")
+    return str(raw) if raw is not None else None
+
+
 class _SharedFeatureflipCore:
     """Internal shared core owning all expensive resources of a FeatureflipClient.
 
@@ -70,6 +85,13 @@ class _SharedFeatureflipCore:
         self._sdk_key = sdk_key
         self._config = config
 
+        # Filter to callables defensively — Python callers bypass the type
+        # hints, and a non-callable entry must be dropped at construction
+        # rather than blowing up on the evaluation hot path.
+        self._inspectors: list[EvaluationInspector] = [
+            inspector for inspector in (config.inspectors or []) if callable(inspector)
+        ]
+
         self._test_mode_values = test_mode_values
         self._test_values: dict[str, Any] = dict(test_mode_values) if test_mode_values else {}
 
@@ -127,12 +149,21 @@ class _SharedFeatureflipCore:
         return cls(sdk_key=None, config=Config(), test_mode_flags=flags)
 
     @classmethod
-    def _create_for_testing_stub(cls, flags: dict[str, Any]) -> _SharedFeatureflipCore:
+    def _create_for_testing_stub(
+        cls,
+        flags: dict[str, Any],
+        inspectors: list[EvaluationInspector] | None = None,
+    ) -> _SharedFeatureflipCore:
         """Create a test-stub core that returns fixed values (no flag evaluation).
 
         This is the backing implementation for ``FeatureflipClient.for_testing``.
+        ``inspectors`` is optional so existing call sites are unaffected.
         """
-        return cls(sdk_key=None, config=Config(), test_mode_values=flags)
+        return cls(
+            sdk_key=None,
+            config=Config(inspectors=list(inspectors) if inspectors else []),
+            test_mode_values=flags,
+        )
 
     # --- Refcount ---
 
@@ -185,7 +216,27 @@ class _SharedFeatureflipCore:
 
         In test-stub mode, returns the fixed value for the given key (or a
         FLAG_NOT_FOUND detail if the key isn't in the stub map).
+
+        This is the single evaluation choke point — every ``variation`` /
+        ``variation_detail`` call funnels through it — so the registered
+        evaluation inspectors are notified here, exactly once per call, with
+        the value and reason the caller actually receives. ``_evaluate``
+        resolves a complete detail on *every* exit path (test-stub hit,
+        test-stub miss, flag-not-found, evaluated result, ``None``-value
+        default substitution, and the error branch), so notifying once around
+        it instruments them all with no risk of a double fire.
         """
+        detail = self._evaluate(key, context, default)
+        self._notify_inspectors(key, context, detail)
+        return detail
+
+    def _evaluate(
+        self,
+        key: str,
+        context: dict[str, Any],
+        default: T,
+    ) -> EvaluationDetail:
+        """Resolve the evaluation detail. Never raises — see ``evaluate``."""
         try:
             # Test-stub mode: short-circuit to fixed values
             if self._test_mode_values is not None:
@@ -208,6 +259,21 @@ class _SharedFeatureflipCore:
                 flag, eval_context, self._get_segment, all_flags=all_flags
             )
 
+            # Malformed config: the evaluator selected a variation key the flag
+            # does not define (e.g. a fallthrough/rule naming a since-deleted
+            # variation). Degrade to the caller's default and report ERROR,
+            # mirroring the engine's ServeVariation + the C#/Java SDKs (#1989).
+            # A variation that genuinely exists with a None value is NOT this
+            # case — hence the key lookup rather than a ``value is None`` check.
+            if detail.variation_key and flag.get_variation(detail.variation_key) is None:
+                return EvaluationDetail(
+                    value=default,
+                    reason=EvaluationReason.ERROR,
+                    rule_id=detail.rule_id,
+                    variation_key=detail.variation_key,
+                    prerequisite_key=detail.prerequisite_key,
+                )
+
             if detail.value is None:
                 return EvaluationDetail(
                     value=default,
@@ -231,6 +297,57 @@ class _SharedFeatureflipCore:
             raise RuntimeError("set_test_value() can only be called on a test-stub core")
         self._test_values[key] = value
 
+    # --- Evaluation inspectors ---
+
+    def _notify_inspectors(
+        self,
+        flag_key: str,
+        context: dict[str, Any],
+        detail: EvaluationDetail,
+    ) -> None:
+        """Fire the registered evaluation inspectors for one evaluation.
+
+        Never raises. Both halves are isolated:
+
+        * Building the event must never disturb evaluation — a caller passing a
+          non-mapping ``context`` (or mutating its own dict concurrently) would
+          otherwise make ``dict(context)`` throw *out of* ``evaluate`` and
+          silently downgrade the caller to their default, purely because an
+          inspector happened to be registered. On failure the notification is
+          skipped and logged.
+        * A throwing inspector is isolated: it neither changes the value the
+          caller receives nor stops the remaining inspectors from firing; the
+          failure is logged and swallowed.
+
+        The event-build guard lives *here*, not around ``_evaluate`` in
+        ``evaluate`` — wrapping the call site would route the failure into the
+        evaluation error handling and could double-fire the inspectors.
+        """
+        # Hot-path guard: with no inspectors registered, allocate nothing.
+        if not self._inspectors:
+            return
+
+        try:
+            event = EvaluationEvent(
+                flag_key=flag_key,
+                # Copy so a buggy inspector can't mutate the caller's context.
+                context=dict(context or {}),
+                value=detail.value,
+                reason=detail.reason,
+                variation_key=detail.variation_key,
+                rule_id=detail.rule_id,
+                prerequisite_key=detail.prerequisite_key,
+            )
+        except Exception as e:
+            logger.warning("inspector_event_build_error", key=flag_key, error=str(e))
+            return
+
+        for inspector in self._inspectors:
+            try:
+                inspector(event)
+            except Exception as e:
+                logger.warning("inspector_error", key=flag_key, error=str(e))
+
     # --- Internal flag store ---
 
     def _get_flag(self, key: str) -> FlagConfiguration | None:
@@ -373,10 +490,13 @@ class _SharedFeatureflipCore:
         """Queue a custom event."""
         if self._test_mode_values is not None or self._event_processor is None:
             return
+        # Send the backend SdkEventDto shape: top-level userId, no `context`.
+        # See apps/evaluation-api Controllers/SdkController.RecordEvents — the
+        # backend has no context/value/reason field, so anything else is dropped.
         event = {
             "type": "Custom",
             "flagKey": event_name,
-            "context": context or {},
+            "userId": _resolve_user_id(context or {}),
             "metadata": metadata or {},
             "timestamp": datetime.now(timezone.utc).isoformat(),
         }
@@ -386,10 +506,19 @@ class _SharedFeatureflipCore:
         """Send user attributes for segment building."""
         if self._test_mode_values is not None or self._event_processor is None:
             return
+        # Promote the user id to the top-level userId field and put the remaining
+        # attributes in metadata (stripping both alias spellings so the identity
+        # isn't duplicated inside the metadata bag).
+        attributes = {
+            k: v
+            for k, v in (context or {}).items()
+            if k not in ("user_id", "userId")
+        }
         event = {
             "type": "Identify",
             "flagKey": "$identify",
-            "context": context or {},
+            "userId": _resolve_user_id(context or {}),
+            "metadata": attributes,
             "timestamp": datetime.now(timezone.utc).isoformat(),
         }
         self._event_processor.queue_event(event)
@@ -402,24 +531,25 @@ class _SharedFeatureflipCore:
     def queue_evaluation_event(
         self,
         key: str,
-        value: Any,
         context: dict[str, Any],
-        reason: EvaluationReason,
-        rule_id: str | None = None,
+        variation_key: str | None,
     ) -> None:
-        """Queue an evaluation event (called by the handle's variation() method)."""
+        """Queue an evaluation event (called by the handle's variation() method).
+
+        Emits the backend SdkEventDto shape — top-level ``userId`` and
+        ``variation`` — mirroring the JS SDK. The backend has no context/value/
+        reason/ruleId fields, so they are not sent (System.Text.Json would drop
+        them and bind UserId/Variation to null; see #1920).
+        """
         if self._event_processor is None:
             return
         event: dict[str, Any] = {
             "type": "Evaluation",
             "flagKey": key,
-            "value": value,
-            "context": context,
-            "reason": reason.value,
+            "userId": _resolve_user_id(context or {}),
+            "variation": variation_key,
             "timestamp": datetime.now(timezone.utc).isoformat(),
         }
-        if rule_id is not None:
-            event["ruleId"] = rule_id
         self._event_processor.queue_event(event)
 
     # --- Shutdown ---
@@ -572,7 +702,12 @@ def _reset_for_testing() -> None:
 
 
 def _configs_equal(a: Config, b: Config) -> bool:
-    """Compare two Config objects by value across all 9 fields."""
+    """Compare two Config objects by value across the 9 comparable fields.
+
+    ``inspectors`` is deliberately excluded: callbacks aren't structurally
+    comparable, and a differing callback must not trigger the "different
+    options" warning for a shared core.
+    """
     return (
         a.base_url == b.base_url
         and a.connect_timeout == b.connect_timeout

{featureflip-2.3.0 → featureflip-2.4.0}/src/featureflip/client.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import os
-from typing import Any, TypeVar, cast
+from typing import TYPE_CHECKING, Any, TypeVar, cast
 
 import structlog
 
@@ -11,6 +11,9 @@ from featureflip._core import _get_or_create_core, _SharedFeatureflipCore
 from featureflip.config import Config
 from featureflip.detail import EvaluationDetail, EvaluationReason
 
+if TYPE_CHECKING:
+    from featureflip.inspector import EvaluationInspector
+
 logger = structlog.get_logger()
 
 T = TypeVar("T")
@@ -103,10 +106,8 @@ class FeatureflipClient:
             if track:
                 self._core.queue_evaluation_event(
                     key=key,
-                    value=value,
                     context=context or {},
-                    reason=detail.reason,
-                    rule_id=detail.rule_id,
+                    variation_key=detail.variation_key,
                 )
             return cast("T", value)
         except Exception as e:
@@ -203,7 +204,11 @@ class FeatureflipClient:
     # --- Test-stub factory ---
 
     @classmethod
-    def for_testing(cls, flags: dict[str, Any]) -> FeatureflipClient:
+    def for_testing(
+        cls,
+        flags: dict[str, Any],
+        inspectors: list[EvaluationInspector] | None = None,
+    ) -> FeatureflipClient:
         """Create a test client with fixed flag values.
 
         The test client:
@@ -215,6 +220,11 @@ class FeatureflipClient:
 
         Args:
             flags: Dictionary mapping flag keys to their values.
+            inspectors: Optional evaluation inspectors, so code under test that
+                relies on inspector side effects can be unit-tested against a
+                stub client. Omitted by default — every existing call site is
+                unaffected. Inspectors fire on both stub exit paths (a stub hit
+                and a stub miss).
 
         Returns:
             A test client instance.
@@ -226,14 +236,29 @@ class FeatureflipClient:
             ... })
             >>> client.variation("feature-a", {}, default=False)
             True
+
+        Example with an inspector:
+            >>> seen = []
+            >>> client = FeatureflipClient.for_testing(
+            ...     {"feature-a": True}, inspectors=[seen.append]
+            ... )
+            >>> client.variation("feature-a", {}, default=False)
+            True
+            >>> seen[0].flag_key
+            'feature-a'
         """
         # Create instance without calling __init__ (same technique the original
         # used). Then wire up a standalone test-stub core that never enters
         # _LIVE_CORES (it has no sdk_key).
+        #
+        # NOTE: this bypasses __init__ entirely, so any change to the client's
+        # constructor shape (new instance attribute, new core wiring) must be
+        # mirrored here or test clients silently drift from real ones — which
+        # is exactly how `inspectors` came to be dropped on this path.
         instance = object.__new__(cls)
         instance._core = _SharedFeatureflipCore(
             sdk_key=None,
-            config=Config(),
+            config=Config(inspectors=list(inspectors) if inspectors else []),
             test_mode_values=dict(flags),
         )
         instance._closed = False
@@ -254,20 +279,15 @@ class FeatureflipClient:
     def _queue_evaluation_event(
         self,
         key: str,
-        value: Any,
         context: dict[str, Any],
-        reason: EvaluationReason,
-        rule_id: str | None = None,
+        variation_key: str | None = None,
     ) -> None:
         """Queue an evaluation event. Delegates to the shared core.
 
-        Preserved for backwards compatibility with existing tests that call
-        this method directly on the client.
+        Preserved for tests that call this method directly on the client.
         """
         self._core.queue_evaluation_event(
             key=key,
-            value=value,
             context=context,
-            reason=reason,
-            rule_id=rule_id,
+            variation_key=variation_key,
         )

{featureflip-2.3.0 → featureflip-2.4.0}/src/featureflip/config.py

@@ -2,7 +2,11 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from featureflip.inspector import EvaluationInspector
 
 
 @dataclass
@@ -19,6 +23,13 @@ class Config:
         flush_interval: Interval in seconds for flushing event batches.
         flush_batch_size: Maximum number of events in a batch before flushing.
         init_timeout: Timeout in seconds for client initialization.
+        inspectors: Callables invoked synchronously with an ``EvaluationEvent``
+            on every flag evaluation. Void observers — the return value is
+            ignored, and a raising inspector cannot affect the evaluated value.
+            Deliberately excluded from the config-equality comparison (see
+            ``_core._configs_equal``): callbacks aren't structurally comparable
+            and a differing callback must not trigger the "different options"
+            warning.
     """
 
     base_url: str = "https://eval.featureflip.io"
@@ -30,6 +41,7 @@ class Config:
     flush_interval: float = 30.0
     flush_batch_size: int = 100
     init_timeout: float = 10.0
+    inspectors: list[EvaluationInspector] = field(default_factory=list)
 
     def __post_init__(self) -> None:
         """Validate and normalize configuration values."""

featureflip-2.4.0/src/featureflip/inspector.py

@@ -0,0 +1,72 @@
+"""Evaluation inspector types for the Featureflip SDK.
+
+An *inspector* is a plain callable invoked synchronously, in-process, on every
+flag evaluation. It receives an :class:`EvaluationEvent` describing what the
+caller actually got back and returns nothing — inspectors are void observers,
+meant for piping exposures into analytics / experimentation tooling with no
+backend dependency.
+
+Register inspectors at client construction::
+
+    from featureflip import Config, FeatureflipClient
+
+    client = FeatureflipClient(
+        sdk_key="sdk-xxx",
+        config=Config(inspectors=[lambda e: posthog.capture("$feature_flag_called", e)]),
+    )
+
+Inspectors are honored on the *first* construction for a given SDK key, like
+every other config option (the shared core is cached per key).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from featureflip.detail import EvaluationReason
+
+
+def _utc_now_iso() -> str:
+    """Return the current UTC time as an ISO-8601 string."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass(frozen=True)
+class EvaluationEvent:
+    """A single flag evaluation, handed to every registered inspector.
+
+    This payload is the frozen cross-SDK inspector contract; the field names
+    mirror the other Featureflip SDKs (adapted to Python's snake_case).
+
+    Attributes:
+        flag_key: The key of the flag that was evaluated.
+        context: A copy of the full evaluation context. Mutating it does not
+            affect the caller's dictionary. Treat as read-only.
+        value: The value the caller actually receives (default already applied).
+        reason: Why this value was served. Uses the Python SDK's native
+            ``EvaluationReason`` enum — each SDK emits its own reason casing.
+        variation_key: The winning variation key. ``None`` when the flag wasn't
+            found or evaluation errored.
+        rule_id: The matched rule's id — set only when the reason is
+            ``RULE_MATCH``.
+        prerequisite_key: The failing prerequisite's flag key — set only when
+            the reason is ``PREREQUISITE_FAILED``.
+        timestamp: ISO-8601 timestamp of the evaluation.
+    """
+
+    flag_key: str
+    context: dict[str, Any]
+    value: Any
+    reason: EvaluationReason
+    variation_key: str | None = None
+    rule_id: str | None = None
+    prerequisite_key: str | None = None
+    timestamp: str = field(default_factory=_utc_now_iso)
+
+
+EvaluationInspector = Callable[["EvaluationEvent"], None]
+"""A void observer invoked once per evaluation with an :class:`EvaluationEvent`."""