optimizely-sdk 5.5.0__tar.gz → 5.6.0__tar.gz

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Optimizely Python SDK Changelog
 
+## 5.6.0
+July 10th, 2026
+
+### New Features
+
+#### **Local Holdouts Support**
+
+- Added local holdouts support to the Python SDK, enabling flag-level traffic exclusion from experiments. ([#512](https://github.com/optimizely/python-sdk/pull/512))
+- Added `localHoldouts` datafile section parsing for backward compatibility with older datafile formats. ([#517](https://github.com/optimizely/python-sdk/pull/517))
+
+---
+
+### Bug Fixes
+
+- Fixed invalid IDs in holdout decision events by normalizing `campaign_id`, `variation_id`, and `entity_id` fields. ([#518](https://github.com/optimizely/python-sdk/pull/518))
+- Fixed CMAB prediction requests to use attribute ID instead of attribute key. ([#520](https://github.com/optimizely/python-sdk/pull/520))
+- Fixed ODP identify events being sent with a single identifier, which is a no-op. ([#513](https://github.com/optimizely/python-sdk/pull/513))
+
+---
+
+
 ## 5.5.0
 April 30th, 2026
 

{optimizely_sdk-5.5.0/optimizely_sdk.egg-info → optimizely_sdk-5.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-sdk
-Version: 5.5.0
+Version: 5.6.0
 Summary: Python SDK for Optimizely Feature Experimentation, Optimizely Full Stack (legacy), and Optimizely Rollouts.
 Home-page: https://github.com/optimizely/python-sdk
 Author: Optimizely
@@ -24,17 +24,17 @@ Requires-Dist: requests>=2.21
 Requires-Dist: idna>=2.10
 Requires-Dist: rpds-py<0.20.0; python_version < "3.11"
 Provides-Extra: test
-Requires-Dist: requests>=2.21; extra == "test"
-Requires-Dist: idna>=2.10; extra == "test"
-Requires-Dist: ruff>=0.15.0; extra == "test"
-Requires-Dist: python-coveralls; extra == "test"
+Requires-Dist: pytest>=6.2.0; extra == "test"
 Requires-Dist: coverage; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
-Requires-Dist: rpds-py<0.20.0; python_version < "3.11" and extra == "test"
 Requires-Dist: jsonschema>=3.2.0; extra == "test"
-Requires-Dist: funcsigs>=0.4; extra == "test"
-Requires-Dist: pytest>=6.2.0; extra == "test"
 Requires-Dist: pyrsistent>=0.16.0; extra == "test"
+Requires-Dist: requests>=2.21; extra == "test"
+Requires-Dist: rpds-py<0.20.0; python_version < "3.11" and extra == "test"
+Requires-Dist: python-coveralls; extra == "test"
+Requires-Dist: funcsigs>=0.4; extra == "test"
+Requires-Dist: idna>=2.10; extra == "test"
+Requires-Dist: ruff>=0.15.0; extra == "test"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -304,6 +304,27 @@ idna (BSD 3-Clause License https://github.com/kjd/idna/blob/master/LICENSE.md)
 - Swift - https://github.com/optimizely/swift-sdk
 # Optimizely Python SDK Changelog
 
+## 5.6.0
+July 10th, 2026
+
+### New Features
+
+#### **Local Holdouts Support**
+
+- Added local holdouts support to the Python SDK, enabling flag-level traffic exclusion from experiments. ([#512](https://github.com/optimizely/python-sdk/pull/512))
+- Added `localHoldouts` datafile section parsing for backward compatibility with older datafile formats. ([#517](https://github.com/optimizely/python-sdk/pull/517))
+
+---
+
+### Bug Fixes
+
+- Fixed invalid IDs in holdout decision events by normalizing `campaign_id`, `variation_id`, and `entity_id` fields. ([#518](https://github.com/optimizely/python-sdk/pull/518))
+- Fixed CMAB prediction requests to use attribute ID instead of attribute key. ([#520](https://github.com/optimizely/python-sdk/pull/520))
+- Fixed ODP identify events being sent with a single identifier, which is a no-op. ([#513](https://github.com/optimizely/python-sdk/pull/513))
+
+---
+
+
 ## 5.5.0
 April 30th, 2026
 

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/cmab/cmab_service.py

@@ -163,7 +163,7 @@ class DefaultCmabService:
         for attribute_id in cmab_attribute_ids:
             attribute = project_config.attribute_id_map.get(attribute_id)
             if attribute and attribute.key in user_attributes:
-                filtered_user_attributes[attribute.key] = user_attributes[attribute.key]
+                filtered_user_attributes[attribute.id] = user_attributes[attribute.key]
 
         return filtered_user_attributes
 

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/decision_service.py

@@ -610,6 +610,24 @@ class DecisionService:
                 return Decision(experiment=rule, variation=forced_decision_variation,
                                 source=enums.DecisionSources.ROLLOUT, cmab_uuid=None), decide_reasons
 
+            # Check local holdouts targeting this specific delivery rule (FSSDK-12369)
+            local_holdouts = project_config.get_holdouts_for_rule(rule.id)
+            for holdout in local_holdouts:
+                local_holdout_decision = self.get_variation_for_holdout(
+                    holdout, user_context, project_config
+                )
+                decide_reasons.extend(local_holdout_decision['reasons'])
+
+                local_decision = local_holdout_decision['decision']
+                if local_decision.variation is not None:
+                    message = (
+                        f"The user '{user_id}' is bucketed into local holdout '{holdout.key}' "
+                        f"for delivery rule '{rule.key}'."
+                    )
+                    self.logger.info(message)
+                    decide_reasons.append(message)
+                    return local_decision, decide_reasons
+
             bucketing_id, bucket_reasons = self._get_bucketing_id(user_id, attributes)
             decide_reasons += bucket_reasons
 
@@ -733,9 +751,9 @@ class DecisionService:
         reasons = decide_reasons.copy() if decide_reasons else []
         user_id = user_context.user_id
 
-        # Check holdouts
-        holdouts = project_config.get_holdouts_for_flag(feature_flag.key)
-        for holdout in holdouts:
+        # Check global holdouts (flag level — before any rules are evaluated)
+        global_holdouts = project_config.get_global_holdouts()
+        for holdout in global_holdouts:
             holdout_decision = self.get_variation_for_holdout(holdout, user_context, project_config)
             reasons.extend(holdout_decision['reasons'])
 
@@ -756,7 +774,7 @@ class DecisionService:
                 'reasons': reasons
             }
 
-        # If no holdout decision, check experiments then rollouts
+        # If no global holdout decision, check experiments then rollouts
         if feature_flag.experimentIds:
             for experiment_id in feature_flag.experimentIds:
                 experiment = project_config.get_experiment_from_id(experiment_id)
@@ -778,6 +796,28 @@ class DecisionService:
                             'reasons': reasons
                         }
 
+                    # Check local holdouts targeting this specific experiment rule (FSSDK-12369)
+                    local_holdouts = project_config.get_holdouts_for_rule(experiment.id)
+                    for holdout in local_holdouts:
+                        local_holdout_decision = self.get_variation_for_holdout(
+                            holdout, user_context, project_config
+                        )
+                        reasons.extend(local_holdout_decision['reasons'])
+
+                        local_decision = local_holdout_decision['decision']
+                        if local_decision.variation is not None:
+                            message = (
+                                f"The user '{user_id}' is bucketed into local holdout '{holdout.key}' "
+                                f"for experiment rule '{experiment.key}'."
+                            )
+                            self.logger.info(message)
+                            reasons.append(message)
+                            return {
+                                'decision': local_holdout_decision['decision'],
+                                'error': False,
+                                'reasons': reasons
+                            }
+
                     # Get variation for experiment
                     variation_result = self.get_variation(
                         project_config, experiment, user_context, user_profile_tracker, reasons, decide_options

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/entities.py

@@ -223,6 +223,7 @@ class Holdout(BaseEntity):
         trafficAllocation: list[TrafficAllocation],
         audienceIds: list[str],
         audienceConditions: Optional[Sequence[str | list[str]]] = None,
+        includedRules: Optional[list[str]] = None,
         **kwargs: Any
     ):
         self.id = id
@@ -232,6 +233,9 @@ class Holdout(BaseEntity):
         self.trafficAllocation = trafficAllocation
         self.audienceIds = audienceIds
         self.audienceConditions = audienceConditions
+        # Per-rule targeting for local holdouts. Scope comes from the datafile
+        # section, not this field; ProjectConfig strips it on 'holdouts' entries.
+        self.included_rules: Optional[list[str]] = includedRules
 
     def get_audience_conditions_or_ids(self) -> Sequence[str | list[str]]:
         """Returns audienceConditions if present, otherwise audienceIds.
@@ -241,6 +245,16 @@ class Holdout(BaseEntity):
         """
         return self.audienceConditions if self.audienceConditions is not None else self.audienceIds
 
+    @property
+    def is_global(self) -> bool:
+        """True if this is a global holdout.
+
+        Scope is set by the datafile section ('holdouts' vs 'localHoldouts').
+        ProjectConfig strips 'includedRules' on 'holdouts' entries, so this
+        property stays consistent with section membership.
+        """
+        return self.included_rules is None
+
     @property
     def is_activated(self) -> bool:
         """Check if the holdout is activated (running).

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/event/event_factory.py

@@ -1,4 +1,4 @@
-# Copyright 2019, 2022, Optimizely
+# Copyright 2019, 2022, 2026, Optimizely
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -18,6 +18,7 @@ from optimizely import entities
 from optimizely.helpers import enums
 from optimizely.helpers import event_tag_utils
 from optimizely.helpers import validator
+from . import event_id_normalizer
 from . import log_event
 from . import payload
 from . import user_event
@@ -134,12 +135,19 @@ class EventFactory:
                 if isinstance(event.experiment, entities.Experiment):
                     experiment_layerId = event.experiment.layerId
 
+            normalized_campaign_id = event_id_normalizer.normalize_campaign_id(
+                experiment_layerId, experiment_id
+            )
+            normalized_variation_id = event_id_normalizer.normalize_variation_id(variation_id)
+
             metadata = payload.Metadata(event.flag_key, event.rule_key,
                                         event.rule_type, variation_key,
                                         event.enabled, event.cmab_uuid)
-            decision = payload.Decision(experiment_layerId, experiment_id, variation_id, metadata)
+            decision = payload.Decision(
+                normalized_campaign_id, experiment_id, normalized_variation_id, metadata
+            )
             snapshot_event = payload.SnapshotEvent(
-                experiment_layerId, event.uuid, cls.ACTIVATE_EVENT_KEY, event.timestamp,
+                normalized_campaign_id, event.uuid, cls.ACTIVATE_EVENT_KEY, event.timestamp,
             )
 
             snapshot = payload.Snapshot([snapshot_event], [decision])

optimizely_sdk-5.6.0/optimizely/event/event_id_normalizer.py

@@ -0,0 +1,93 @@
+# Copyright 2026, Optimizely
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Normalization helpers for decision-event ID fields.
+
+This module provides byte-equivalent, cross-SDK normalization for the
+``campaign_id``, ``variation_id``, and impression ``entity_id`` fields that
+appear in dispatched decision events.
+
+Rules:
+  * ``campaign_id`` and impression ``entity_id`` accept **any non-empty
+    string** (numeric like ``"12345"`` or opaque like ``"default-12345"`` /
+    ``"layer_abc"``). The fallback to ``experiment_id`` fires ONLY when the
+    value is the empty string, ``None``, or missing. Non-string types are
+    out of scope for this normalization path (the upstream datafile
+    producer delivers string or null values).
+  * ``variation_id`` retains the stricter contract: it MUST be a non-empty
+    string of decimal digits ``0-9`` (leading zeros allowed). Empty,
+    whitespace, non-string, and non-numeric inputs are normalized to
+    ``None`` so the wire payload carries an explicit null.
+  * ``entity_id`` on impression events shares the campaign_id normalization
+    and is therefore byte-equivalent to the normalized campaign_id for the
+    same impression.
+
+The normalization path MUST NOT log, warn, or raise. It must never drop or
+defer event dispatch.
+"""
+
+
+from sys import version_info
+from typing import Any, Optional
+
+if version_info < (3, 10):
+    from typing_extensions import TypeGuard
+else:
+    from typing import TypeGuard
+
+
+def is_non_empty_string(value: Any) -> TypeGuard[str]:
+    """Return ``True`` if ``value`` is a non-empty :class:`str`.
+    Any non-empty string is accepted regardless of
+    character content (IDs may be opaque, e.g. ``"default-12345"``).
+    """
+    return isinstance(value, str) and value != ''
+
+
+def is_numeric_id_string(value: Any) -> TypeGuard[str]:
+    """Return ``True`` if ``value`` is a non-empty decimal-digit string.
+    Whitespace, signs, decimal points, exponents
+    and non-string types all return ``False``. Leading
+    zeros are accepted.
+    """
+    if not isinstance(value, str):
+        return False
+    if value == '':
+        return False
+    return value.isascii() and value.isdigit()
+
+
+def normalize_campaign_id(campaign_id: Any, experiment_id: Any) -> str:
+    """Normalize a decision-event ``campaign_id``.
+
+    Returns ``campaign_id`` unchanged when it is a non-empty string (any
+    character content — numeric like ``"12345"`` or opaque like
+    ``"default-12345"``). Otherwise falls back to ``experiment_id`` (when it
+    is itself a non-empty string). If neither is a non-empty string, returns
+    an empty string so the event still dispatches.
+    """
+    if is_non_empty_string(campaign_id):
+        return campaign_id
+    if is_non_empty_string(experiment_id):
+        return experiment_id
+    return ''
+
+
+def normalize_variation_id(variation_id: Any) -> Optional[str]:
+    """Normalize a decision-event ``variation_id``.
+
+    Returns the original value if it is a valid numeric ID string. Otherwise
+    returns ``None`` so the event payload carries an explicit null for the
+    downstream consumer.
+    """
+    return variation_id if is_numeric_id_string(variation_id) else None

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/event/payload.py

@@ -1,4 +1,4 @@
-# Copyright 2019, 2022, Optimizely
+# Copyright 2019, 2022, 2026, Optimizely
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -71,7 +71,13 @@ class EventBatch:
 class Decision:
     """ Class respresenting Decision. """
 
-    def __init__(self, campaign_id: str, experiment_id: str, variation_id: str, metadata: Metadata):
+    def __init__(
+        self,
+        campaign_id: str,
+        experiment_id: str,
+        variation_id: Optional[str],
+        metadata: Metadata,
+    ):
         self.campaign_id = campaign_id
         self.experiment_id = experiment_id
         self.variation_id = variation_id

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/event_builder.py

@@ -1,4 +1,4 @@
-# Copyright 2016-2019, 2022, Optimizely
+# Copyright 2016-2019, 2022, 2026, Optimizely
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -18,6 +18,7 @@ import uuid
 from sys import version_info
 
 from . import version
+from .event import event_id_normalizer
 from .helpers import enums
 from .helpers import event_tag_utils
 from .helpers import validator
@@ -178,7 +179,7 @@ class EventBuilder:
 
     def _get_required_params_for_impression(
         self, experiment: Experiment, variation_id: str
-    ) -> dict[str, list[dict[str, str | int]]]:
+    ) -> dict[str, list[dict[str, Any]]]:
         """ Get parameters that are required for the impression event to register.
 
     Args:
@@ -188,19 +189,24 @@ class EventBuilder:
     Returns:
       Dict consisting of decisions and events info for impression event.
     """
-        snapshot: dict[str, list[dict[str, str | int]]] = {}
+        snapshot: dict[str, list[dict[str, Any]]] = {}
+
+        normalized_campaign_id = event_id_normalizer.normalize_campaign_id(
+            experiment.layerId, experiment.id
+        )
+        normalized_variation_id = event_id_normalizer.normalize_variation_id(variation_id)
 
         snapshot[self.EventParams.DECISIONS] = [
             {
                 self.EventParams.EXPERIMENT_ID: experiment.id,
-                self.EventParams.VARIATION_ID: variation_id,
-                self.EventParams.CAMPAIGN_ID: experiment.layerId,
+                self.EventParams.VARIATION_ID: normalized_variation_id,
+                self.EventParams.CAMPAIGN_ID: normalized_campaign_id,
             }
         ]
 
         snapshot[self.EventParams.EVENTS] = [
             {
-                self.EventParams.EVENT_ID: experiment.layerId,
+                self.EventParams.EVENT_ID: normalized_campaign_id,
                 self.EventParams.TIME: self._get_time(),
                 self.EventParams.KEY: 'campaign_activated',
                 self.EventParams.UUID: str(uuid.uuid4()),

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/helpers/types.py

@@ -130,3 +130,6 @@ class HoldoutDict(ExperimentDict):
     Extends ExperimentDict with holdout-specific properties.
     """
     holdoutStatus: HoldoutStatus
+    # Per-rule targeting for local holdouts. Scope comes from the datafile section,
+    # not this field; required on 'localHoldouts' entries, stripped on 'holdouts'.
+    includedRules: Optional[list[str]]

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/odp/odp_event_manager.py

@@ -267,9 +267,30 @@ class OdpEventManager:
         except Full:
             self.logger.warning(Errors.ODP_EVENT_FAILED.format("Queue is full"))
 
-    def identify_user(self, user_id: str) -> None:
+    def identify_user(self, identifiers: dict[str, str]) -> None:
+        """Send an identify event to ODP if there are multiple valid identifiers.
+
+        An identify event is only useful when there are two or more identifiers
+        to link together in the ODP user profile. Sending a single identifier
+        provides no linking value and wastes a network call.
+
+        Args:
+            identifiers: A dictionary of identifier key-value pairs
+                (e.g. {"fs_user_id": "abc", "email": "a@b.com"}).
+        """
+        # Filter out identifiers with None or empty string values.
+        valid_identifiers = {k: v for k, v in identifiers.items() if v}
+
+        # Identify requires 2+ identifiers to link (e.g., vuid + fs_user_id).
+        # A single identifier has no cross-reference value and generates unnecessary traffic.
+        if len(valid_identifiers) < 2:
+            self.logger.debug(
+                'ODP identify event is not dispatched (fewer than 2 valid identifiers).'
+            )
+            return
+
         self.send_event(OdpManagerConfig.EVENT_TYPE, 'identified',
-                        {OdpManagerConfig.KEY_FOR_USER_ID: user_id}, {})
+                        valid_identifiers, {})
 
     def update_config(self) -> None:
         """Adds update config signal to event_queue."""

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/odp/odp_manager.py

@@ -73,7 +73,7 @@ class OdpManager:
 
         return self.segment_manager.fetch_qualified_segments(user_key, user_value, options)
 
-    def identify_user(self, user_id: str) -> None:
+    def identify_user(self, identifiers: dict[str, str]) -> None:
         if not self.enabled or not self.event_manager:
             self.logger.debug('ODP identify event is not dispatched (ODP disabled).')
             return
@@ -81,7 +81,7 @@ class OdpManager:
             self.logger.debug('ODP identify event is not dispatched (ODP not integrated).')
             return
 
-        self.event_manager.identify_user(user_id)
+        self.event_manager.identify_user(identifiers)
 
     def send_event(self, type: str, action: str, identifiers: dict[str, str], data: dict[str, Any]) -> None:
         """

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/optimizely.py

@@ -1541,7 +1541,7 @@ class Optimizely:
             config.all_segments
         )
 
-    def _identify_user(self, user_id: str) -> None:
+    def _identify_user(self, identifiers: dict[str, str]) -> None:
         if not self.is_valid:
             self.logger.error(enums.Errors.INVALID_OPTIMIZELY.format('identify_user'))
             return
@@ -1551,7 +1551,7 @@ class Optimizely:
             self.logger.error(enums.Errors.INVALID_PROJECT_CONFIG.format('identify_user'))
             return
 
-        self.odp_manager.identify_user(user_id)
+        self.odp_manager.identify_user(identifiers)
 
     def _fetch_qualified_segments(self, user_id: str, options: Optional[list[str]] = None) -> Optional[list[str]]:
         if not self.is_valid:

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/optimizely_user_context.py

@@ -19,6 +19,7 @@ import threading
 from typing import TYPE_CHECKING, Any, Callable, Optional, NewType, Dict
 
 from optimizely.decision import optimizely_decision
+from optimizely.helpers.enums import OdpManagerConfig
 
 if TYPE_CHECKING:
     # prevent circular dependency by skipping import at runtime
@@ -73,7 +74,8 @@ class OptimizelyUserContext:
         ] = {}
 
         if self.client and identify:
-            self.client._identify_user(user_id)
+            identifiers = {OdpManagerConfig.KEY_FOR_USER_ID: user_id}
+            self.client._identify_user(identifiers)
 
     class OptimizelyDecisionContext:
         """ Using class with attributes here instead of namedtuple because

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/project_config.py

@@ -90,14 +90,49 @@ class ProjectConfig:
         self.region: str = region_value or 'US'
 
         # Parse holdouts from datafile and convert to Holdout entities
-        holdouts_data: list[types.HoldoutDict] = config.get('holdouts', [])
+        global_holdouts_data: list[types.HoldoutDict] = config.get('holdouts', [])
+        local_holdouts_data: list[types.HoldoutDict] = config.get('localHoldouts', [])
         self.holdouts: list[entities.Holdout] = []
         self.holdout_id_map: dict[str, entities.Holdout] = {}
-        self.flag_holdouts_map: dict[str, list[entities.Holdout]] = {}
+        # Global holdouts — evaluated at flag level before any rule
+        self.global_holdouts: list[entities.Holdout] = []
+        # Rule-level holdouts — map from rule ID to holdouts targeting that rule
+        self.rule_holdouts_map: dict[str, list[entities.Holdout]] = {}
+
+        # Process global holdouts: section membership is the sole signal for scope.
+        # Drop any 'includedRules' field on entries here so the entity is unambiguously
+        # global (is_global → True), even if the datafile incorrectly includes one.
+        for holdout_data in global_holdouts_data:
+            sanitized = cast(types.HoldoutDict, dict(holdout_data))
+            if sanitized.pop('includedRules', None) is not None:  # type: ignore[misc]
+                self.logger.warning(
+                    f'Global holdout "{holdout_data.get("key", "")}" '
+                    f'(id: {holdout_data.get("id", "<unknown>")}) has "includedRules" '
+                    f'which will be ignored; global holdouts apply to all flags.'
+                )
+            holdout = entities.Holdout(**sanitized)
+            self.holdouts.append(holdout)
+
+            # Only process Running holdouts
+            if not holdout.is_activated:
+                continue
+
+            # Map by ID for quick lookup
+            self.holdout_id_map[holdout.id] = holdout
+            self.global_holdouts.append(holdout)
+
+        # Process local holdouts: every entry must carry 'includedRules' (list of rule IDs).
+        # Entries without 'includedRules' are invalid — log an error and exclude
+        # them from evaluation (do NOT fall back to global application).
+        for holdout_data in local_holdouts_data:
+            if 'includedRules' not in holdout_data or holdout_data.get('includedRules') is None:
+                holdout_id = holdout_data.get('id', '<unknown>')
+                self.logger.error(
+                    f'Local holdout with ID "{holdout_id}" is missing required "includedRules" '
+                    f'field and will be excluded from evaluation.'
+                )
+                continue
 
-        # Convert holdout dicts to Holdout entities
-        for holdout_data in holdouts_data:
-            # Create Holdout entity
             holdout = entities.Holdout(**holdout_data)
             self.holdouts.append(holdout)
 
@@ -108,6 +143,12 @@ class ProjectConfig:
             # Map by ID for quick lookup
             self.holdout_id_map[holdout.id] = holdout
 
+            # Register for each targeted rule ID
+            for rule_id in (holdout.included_rules or []):
+                if rule_id not in self.rule_holdouts_map:
+                    self.rule_holdouts_map[rule_id] = []
+                self.rule_holdouts_map[rule_id].append(holdout)
+
         # Utility maps for quick lookup
         self.group_id_map: dict[str, entities.Group] = self._generate_key_map(self.groups, 'id', entities.Group)
         self.experiment_id_map: dict[str, entities.Experiment] = self._generate_key_map(
@@ -240,11 +281,6 @@ class ProjectConfig:
                             everyone_else_variation.variables, 'id', entities.Variation.VariableUsage
                         )
 
-            # Map all running holdouts to this flag
-            applicable_holdouts = list(self.holdout_id_map.values())
-            if applicable_holdouts:
-                self.flag_holdouts_map[feature.key] = applicable_holdouts
-
             rollout = None if len(feature.rolloutId) == 0 else self.rollout_id_map[feature.rolloutId]
             if rollout:
                 for exp in rollout.experiments:
@@ -878,19 +914,34 @@ class ProjectConfig:
 
         return None
 
-    def get_holdouts_for_flag(self, flag_key: str) -> list[entities.Holdout]:
-        """ Helper method to get holdouts from an applied feature flag.
+    def get_global_holdouts(self) -> list[entities.Holdout]:
+        """Return all global holdouts (parsed from the top-level 'holdouts' section).
 
-        Args:
-            flag_key: Key of the feature flag.
+        Global holdouts are evaluated at flag level before any rule is checked.
+        Section membership in 'holdouts' is the sole signal for global scope —
+        any 'includedRules' field on these entries is ignored.
 
         Returns:
-            The holdouts that apply for a specific flag as Holdout entity objects.
+            List of global Holdout entities that are currently running.
         """
-        if not self.holdouts:
-            return []
+        return self.global_holdouts
+
+    def get_holdouts_for_rule(self, rule_id: str) -> list[entities.Holdout]:
+        """Return local holdouts that target a specific rule.
 
-        return self.flag_holdouts_map.get(flag_key, [])
+        Local holdouts come from the top-level 'localHoldouts' datafile section and
+        are scoped per-rule via their 'includedRules' field. They are evaluated
+        before the rule's audience and traffic allocation checks. A rule ID not
+        present in any holdout's includedRules simply returns an empty list —
+        silently skipped.
+
+        Args:
+            rule_id: The experiment or delivery rule ID to look up.
+
+        Returns:
+            List of local Holdout entities targeting the given rule ID.
+        """
+        return self.rule_holdouts_map.get(rule_id, [])
 
     def get_holdout(self, holdout_id: str) -> Optional[entities.Holdout]:
         """ Helper method to get holdout from holdout ID.

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely/version.py

@@ -11,5 +11,5 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-version_info = (5, 5, 0)
+version_info = (5, 6, 0)
 __version__ = '.'.join(str(v) for v in version_info)

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0/optimizely_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-sdk
-Version: 5.5.0
+Version: 5.6.0
 Summary: Python SDK for Optimizely Feature Experimentation, Optimizely Full Stack (legacy), and Optimizely Rollouts.
 Home-page: https://github.com/optimizely/python-sdk
 Author: Optimizely
@@ -24,17 +24,17 @@ Requires-Dist: requests>=2.21
 Requires-Dist: idna>=2.10
 Requires-Dist: rpds-py<0.20.0; python_version < "3.11"
 Provides-Extra: test
-Requires-Dist: requests>=2.21; extra == "test"
-Requires-Dist: idna>=2.10; extra == "test"
-Requires-Dist: ruff>=0.15.0; extra == "test"
-Requires-Dist: python-coveralls; extra == "test"
+Requires-Dist: pytest>=6.2.0; extra == "test"
 Requires-Dist: coverage; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
-Requires-Dist: rpds-py<0.20.0; python_version < "3.11" and extra == "test"
 Requires-Dist: jsonschema>=3.2.0; extra == "test"
-Requires-Dist: funcsigs>=0.4; extra == "test"
-Requires-Dist: pytest>=6.2.0; extra == "test"
 Requires-Dist: pyrsistent>=0.16.0; extra == "test"
+Requires-Dist: requests>=2.21; extra == "test"
+Requires-Dist: rpds-py<0.20.0; python_version < "3.11" and extra == "test"
+Requires-Dist: python-coveralls; extra == "test"
+Requires-Dist: funcsigs>=0.4; extra == "test"
+Requires-Dist: idna>=2.10; extra == "test"
+Requires-Dist: ruff>=0.15.0; extra == "test"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -304,6 +304,27 @@ idna (BSD 3-Clause License https://github.com/kjd/idna/blob/master/LICENSE.md)
 - Swift - https://github.com/optimizely/swift-sdk
 # Optimizely Python SDK Changelog
 
+## 5.6.0
+July 10th, 2026
+
+### New Features
+
+#### **Local Holdouts Support**
+
+- Added local holdouts support to the Python SDK, enabling flag-level traffic exclusion from experiments. ([#512](https://github.com/optimizely/python-sdk/pull/512))
+- Added `localHoldouts` datafile section parsing for backward compatibility with older datafile formats. ([#517](https://github.com/optimizely/python-sdk/pull/517))
+
+---
+
+### Bug Fixes
+
+- Fixed invalid IDs in holdout decision events by normalizing `campaign_id`, `variation_id`, and `entity_id` fields. ([#518](https://github.com/optimizely/python-sdk/pull/518))
+- Fixed CMAB prediction requests to use attribute ID instead of attribute key. ([#520](https://github.com/optimizely/python-sdk/pull/520))
+- Fixed ODP identify events being sent with a single identifier, which is a no-op. ([#513](https://github.com/optimizely/python-sdk/pull/513))
+
+---
+
+
 ## 5.5.0
 April 30th, 2026
 

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely_sdk.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ optimizely/decision/optimizely_decision.py
 optimizely/decision/optimizely_decision_message.py
 optimizely/event/__init__.py
 optimizely/event/event_factory.py
+optimizely/event/event_id_normalizer.py
 optimizely/event/event_processor.py
 optimizely/event/log_event.py
 optimizely/event/payload.py

{optimizely_sdk-5.5.0 → optimizely_sdk-5.6.0}/optimizely_sdk.egg-info/requires.txt

@@ -7,16 +7,16 @@ idna>=2.10
 rpds-py<0.20.0
 
 [test]
-requests>=2.21
-idna>=2.10
-ruff>=0.15.0
-python-coveralls
+pytest>=6.2.0
 coverage
 pytest-cov
 jsonschema>=3.2.0
-funcsigs>=0.4
-pytest>=6.2.0
 pyrsistent>=0.16.0
+requests>=2.21
+python-coveralls
+funcsigs>=0.4
+idna>=2.10
+ruff>=0.15.0
 
 [test:python_version < "3.11"]
 rpds-py<0.20.0