devcycle-python-server-sdk 3.11.3__py3-none-any.whl → 3.12.0__py3-none-any.whl

devcycle_python_sdk/VERSION.txt

@@ -1 +1 @@
-3.11.3
+3.12.0

devcycle_python_sdk/api/bucketing_client.py

@@ -15,6 +15,7 @@ from devcycle_python_sdk.models.event import DevCycleEvent
 from devcycle_python_sdk.models.feature import Feature
 from devcycle_python_sdk.models.user import DevCycleUser
 from devcycle_python_sdk.models.variable import Variable
+from devcycle_python_sdk.models.eval_reason import EvalReason
 from devcycle_python_sdk.util.strings import slash_join
 
 logger = logging.getLogger(__name__)
@@ -91,11 +92,17 @@ class BucketingAPIClient:
     def variable(self, key: str, user: DevCycleUser) -> Variable:
         data = self.request("POST", self._url("variables", key), json=user.to_json())
 
+        eval_data = data.get("eval")
+        eval_reason = None
+        if eval_data is not None and isinstance(eval_data, dict):
+            eval_reason = EvalReason.from_json(eval_data)
+
         return Variable(
             _id=data.get("_id"),
             key=data.get("key", ""),
             type=data.get("type", ""),
             value=data.get("value"),
+            eval=eval_reason,
         )
 
     def variables(self, user: DevCycleUser) -> Dict[str, Variable]:
@@ -109,6 +116,11 @@ class BucketingAPIClient:
                 type=str(value.get("type")),
                 value=value.get("value"),
                 isDefaulted=None,
+                eval=(
+                    EvalReason.from_json(value.get("eval"))
+                    if value.get("eval")
+                    else None
+                ),
             )
 
         return result

devcycle_python_sdk/api/local_bucketing.py

@@ -22,7 +22,6 @@ from wasmtime import (
 import devcycle_python_sdk.protobuf.utils as pb_utils
 import devcycle_python_sdk.protobuf.variableForUserParams_pb2 as pb2
 from devcycle_python_sdk.exceptions import (
-    VariableTypeMismatchError,
     MalformedConfigError,
 )
 from devcycle_python_sdk.models.bucketed_config import BucketedConfig
@@ -324,13 +323,6 @@ class LocalBucketing:
                 sdk_variable = pb2.SDKVariable_PB()
                 sdk_variable.ParseFromString(var_bytes)
 
-                if sdk_variable.type != pb_variable_type:
-                    # this situation should never actually happen because the WASM handles
-                    # it internally and returns a null value from the WASM function
-                    # This check is here just in case that logic changes in the future
-                    raise VariableTypeMismatchError(
-                        f"Variable returned does not match requested type: {pb_variable_type}"
-                    )
                 return pb_utils.create_variable(sdk_variable, default_value)
 
     def generate_bucketed_config(self, user: DevCycleUser) -> BucketedConfig:

devcycle_python_sdk/cloud_client.py

@@ -9,6 +9,16 @@ from devcycle_python_sdk.exceptions import (
     NotFoundError,
     CloudClientUnauthorizedError,
 )
+from devcycle_python_sdk.managers.eval_hooks_manager import (
+    EvalHooksManager,
+    BeforeHookError,
+    AfterHookError,
+)
+from devcycle_python_sdk.models.eval_reason import (
+    DefaultReasonDetails,
+)
+from devcycle_python_sdk.models.eval_hook import EvalHook
+from devcycle_python_sdk.models.eval_hook_context import HookContext
 from devcycle_python_sdk.models.user import DevCycleUser
 from devcycle_python_sdk.models.event import DevCycleEvent
 from devcycle_python_sdk.models.variable import Variable
@@ -45,6 +55,9 @@ class DevCycleCloudClient(AbstractDevCycleClient):
         self.sdk_type = "server"
         self.bucketing_api = BucketingAPIClient(sdk_key, self.options)
         self._openfeature_provider = DevCycleProvider(self)
+        self.eval_hooks_manager = EvalHooksManager(
+            None if options is None else options.eval_hooks
+        )
 
     def get_sdk_platform(self) -> str:
         return "Cloud"
@@ -87,21 +100,47 @@ class DevCycleCloudClient(AbstractDevCycleClient):
         if default_value is None:
             raise ValueError("Missing parameter: defaultValue")
 
+        context = HookContext(key, user, default_value)
+        variable = Variable.create_default_variable(
+            key=key, default_value=default_value
+        )
+
         try:
-            variable = self.bucketing_api.variable(key, user)
+            before_hook_error = None
+            try:
+                changed_context = self.eval_hooks_manager.run_before(context)
+                if changed_context is not None:
+                    context = changed_context
+            except BeforeHookError as e:
+                before_hook_error = e
+            variable = self.bucketing_api.variable(key, context.user)
+            if before_hook_error is None:
+                self.eval_hooks_manager.run_after(context, variable)
+            else:
+                raise before_hook_error
         except CloudClientUnauthorizedError as e:
             logger.warning("DevCycle: SDK key is invalid, unable to make cloud request")
             raise e
         except NotFoundError:
             logger.warning(f"DevCycle: Variable not found: {key}")
             return Variable.create_default_variable(
-                key=key, default_value=default_value
+                key=key,
+                default_value=default_value,
+                default_reason_detail=DefaultReasonDetails.MISSING_VARIABLE,
             )
+        except BeforeHookError as e:
+            self.eval_hooks_manager.run_error(context, e)
+        except AfterHookError as e:
+            self.eval_hooks_manager.run_error(context, e)
         except Exception as e:
             logger.error(f"DevCycle: Error evaluating variable: {e}")
             return Variable.create_default_variable(
-                key=key, default_value=default_value
+                key=key,
+                default_value=default_value,
+                default_reason_detail=DefaultReasonDetails.ERROR,
             )
+        finally:
+            self.eval_hooks_manager.run_finally(context, variable)
 
         variable.defaultValue = default_value
 
@@ -111,7 +150,9 @@ class DevCycleCloudClient(AbstractDevCycleClient):
                 f"DevCycle: Variable {key} is type {type(variable.value)}, but default value is type {type(default_value)}",
             )
             return Variable.create_default_variable(
-                key=key, default_value=default_value
+                key=key,
+                default_value=default_value,
+                default_reason_detail=DefaultReasonDetails.TYPE_MISMATCH,
             )
 
         return variable
@@ -189,6 +230,12 @@ class DevCycleCloudClient(AbstractDevCycleClient):
         # Cloud client doesn't need to release any resources
         logger.debug("DevCycle: Cloud client closed")
 
+    def add_hook(self, hook: EvalHook) -> None:
+        self.eval_hooks_manager.add_hook(hook)
+
+    def clear_hooks(self) -> None:
+        self.eval_hooks_manager.clear_hooks()
+
 
 def _validate_sdk_key(sdk_key: str) -> None:
     if sdk_key is None or len(sdk_key) == 0:

devcycle_python_sdk/local_client.py

@@ -6,10 +6,21 @@ from typing import Any, Dict, Union, Optional
 
 from devcycle_python_sdk import DevCycleLocalOptions, AbstractDevCycleClient
 from devcycle_python_sdk.api.local_bucketing import LocalBucketing
-from devcycle_python_sdk.exceptions import VariableTypeMismatchError
 from devcycle_python_sdk.managers.config_manager import EnvironmentConfigManager
+from devcycle_python_sdk.managers.eval_hooks_manager import (
+    EvalHooksManager,
+    BeforeHookError,
+    AfterHookError,
+)
 from devcycle_python_sdk.managers.event_queue_manager import EventQueueManager
 from devcycle_python_sdk.models.bucketed_config import BucketedConfig
+from devcycle_python_sdk.models.eval_hook import EvalHook
+from devcycle_python_sdk.models.eval_hook_context import HookContext
+from devcycle_python_sdk.models.eval_reason import (
+    DefaultReasonDetails,
+    EvalReason,
+    EvalReasons,
+)
 from devcycle_python_sdk.models.event import DevCycleEvent, EventType
 from devcycle_python_sdk.models.feature import Feature
 from devcycle_python_sdk.models.platform_data import default_platform_data
@@ -51,6 +62,7 @@ class DevCycleLocalClient(AbstractDevCycleClient):
         )
 
         self._openfeature_provider: Optional[DevCycleProvider] = None
+        self.eval_hooks_manager = EvalHooksManager(self.options.eval_hooks)
 
     def get_sdk_platform(self) -> str:
         return "Local"
@@ -123,7 +135,10 @@ class DevCycleLocalClient(AbstractDevCycleClient):
             try:
                 self.event_queue_manager.queue_aggregate_event(
                     event=DevCycleEvent(
-                        type=EventType.AggVariableDefaulted, target=key, value=1
+                        type=EventType.AggVariableDefaulted,
+                        target=key,
+                        value=1,
+                        metaData={"evalReason": EvalReasons.DEFAULT},
                     ),
                     bucketed_config=None,
                 )
@@ -131,20 +146,54 @@ class DevCycleLocalClient(AbstractDevCycleClient):
                 logger.warning(
                     f"DevCycle: Unable to track AggVariableDefaulted event for Variable {key}: {e}"
                 )
-            return Variable.create_default_variable(key, default_value)
+            return Variable.create_default_variable(
+                key, default_value, DefaultReasonDetails.MISSING_CONFIG
+            )
+
+        context = HookContext(key, user, default_value)
+        variable = Variable.create_default_variable(
+            key=key, default_value=default_value
+        )
 
         try:
-            variable = self.local_bucketing.get_variable_for_user_protobuf(
+            before_hook_error = None
+            try:
+                changed_context = self.eval_hooks_manager.run_before(context)
+                if changed_context is not None:
+                    context = changed_context
+            except BeforeHookError as e:
+                before_hook_error = e
+            bucketed_variable = self.local_bucketing.get_variable_for_user_protobuf(
                 user, key, default_value
             )
-            if variable:
-                return variable
-        except VariableTypeMismatchError:
-            logger.debug("DevCycle: Variable type mismatch, returning default value")
+            if bucketed_variable is not None:
+                variable = bucketed_variable
+            else:
+                variable.eval = EvalReason(
+                    reason=EvalReasons.DEFAULT,
+                    details=DefaultReasonDetails.USER_NOT_TARGETED,
+                )
+
+            if before_hook_error is None:
+                self.eval_hooks_manager.run_after(context, variable)
+            else:
+                raise before_hook_error
         except Exception as e:
-            logger.warning(f"DevCycle: Error retrieving variable for user: {e}")
+            variable.eval = EvalReason(
+                reason=EvalReasons.DEFAULT, details=DefaultReasonDetails.ERROR
+            )
+
+            if isinstance(e, BeforeHookError):
+                self.eval_hooks_manager.run_error(context, e)
+            elif isinstance(e, AfterHookError):
+                self.eval_hooks_manager.run_error(context, e)
+            else:
+                logger.warning(f"DevCycle: Error retrieving variable for user: {e}")
 
-        return Variable.create_default_variable(key, default_value)
+            return variable
+        finally:
+            self.eval_hooks_manager.run_finally(context, variable)
+        return variable
 
     def _generate_bucketed_config(self, user: DevCycleUser) -> BucketedConfig:
         """
@@ -169,8 +218,6 @@ class DevCycleLocalClient(AbstractDevCycleClient):
             )
             return {}
 
-        variable_map: Dict[str, Variable] = {}
-
         try:
             return self.local_bucketing.generate_bucketed_config(user).variables
         except Exception as e:
@@ -179,8 +226,6 @@ class DevCycleLocalClient(AbstractDevCycleClient):
             )
             return {}
 
-        return variable_map
-
     def all_features(self, user: DevCycleUser) -> Dict[str, Feature]:
         """
         Returns all segmented and bucketed features for a user.  This method will return an empty map if the client has not been initialized or if the user is not bucketed into any features
@@ -234,6 +279,12 @@ class DevCycleLocalClient(AbstractDevCycleClient):
         self.config_manager.close()
         self.event_queue_manager.close()
 
+    def add_hook(self, eval_hook: EvalHook) -> None:
+        self.eval_hooks_manager.add_hook(eval_hook)
+
+    def clear_hooks(self) -> None:
+        self.eval_hooks_manager.clear_hooks()
+
 
 def _validate_sdk_key(sdk_key: str) -> None:
     if sdk_key is None or len(sdk_key) == 0:

devcycle_python_sdk/managers/eval_hooks_manager.py

@@ -0,0 +1,73 @@
+from typing import List, Optional
+
+from devcycle_python_sdk.models.eval_hook import EvalHook
+from devcycle_python_sdk.models.eval_hook_context import HookContext
+from devcycle_python_sdk.models.variable import Variable
+from devcycle_python_sdk.options import logger
+
+
+class BeforeHookError(Exception):
+    """Exception raised when a before hook fails"""
+
+    def __init__(self, message: str, original_error: Exception):
+        self.message = message
+        self.original_error = original_error
+        super().__init__(self.message)
+
+
+class AfterHookError(Exception):
+    """Exception raised when an after hook fails"""
+
+    def __init__(self, message: str, original_error: Exception):
+        self.message = message
+        self.original_error = original_error
+        super().__init__(self.message)
+
+
+class EvalHooksManager:
+    def __init__(self, hooks: Optional[List[EvalHook]] = None):
+        self.hooks: List[EvalHook] = hooks if hooks is not None else []
+
+    def add_hook(self, hook: EvalHook) -> None:
+        """Add an evaluation hook to be executed"""
+        self.hooks.append(hook)
+
+    def clear_hooks(self) -> None:
+        """Clear all evaluation hooks"""
+        self.hooks = []
+
+    def run_before(self, context: HookContext) -> Optional[HookContext]:
+        """Run before hooks and return modified context if any"""
+        modified_context = context
+        for hook in self.hooks:
+            try:
+                result = hook.before(modified_context)
+                if result:
+                    modified_context = result
+            except Exception as e:
+                raise BeforeHookError(f"Before hook failed: {e}", e)
+        return modified_context
+
+    def run_after(self, context: HookContext, variable: Variable) -> None:
+        """Run after hooks with the evaluation result"""
+        for hook in self.hooks:
+            try:
+                hook.after(context, variable)
+            except Exception as e:
+                raise AfterHookError(f"After hook failed: {e}", e)
+
+    def run_finally(self, context: HookContext, variable: Optional[Variable]) -> None:
+        """Run finally hooks after evaluation completes"""
+        for hook in self.hooks:
+            try:
+                hook.on_finally(context, variable)
+            except Exception as e:
+                logger.error(f"Error running finally hook: {e}")
+
+    def run_error(self, context: HookContext, error: Exception) -> None:
+        """Run error hooks when an error occurs"""
+        for hook in self.hooks:
+            try:
+                hook.error(context, error)
+            except Exception as e:
+                logger.error(f"Error running error hook: {e}")

devcycle_python_sdk/managers/sse_manager.py

@@ -43,7 +43,7 @@ class SSEManager:
                 elif isinstance(event, ld_eventsource.actions.Event):
                     handle_message(event)
         except Exception as e:
-            logger.exception(f"DevCycle: failed to read SSE message: {e}")
+            logger.debug(f"DevCycle: failed to read SSE message: {e}")
 
     def update(self, config: dict):
         if self.use_new_config(config["sse"]):

devcycle_python_sdk/models/bucketed_config.py

@@ -1,4 +1,3 @@
-# ruff: noqa: N815
 from dataclasses import dataclass
 from typing import Dict, List
 from typing import Optional

devcycle_python_sdk/models/eval_hook.py

@@ -0,0 +1,18 @@
+from typing import Callable, Optional
+
+from devcycle_python_sdk.models.eval_hook_context import HookContext
+from devcycle_python_sdk.models.variable import Variable
+
+
+class EvalHook:
+    def __init__(
+        self,
+        before: Callable[[HookContext], Optional[HookContext]],
+        after: Callable[[HookContext, Variable], None],
+        on_finally: Callable[[HookContext, Optional[Variable]], None],
+        error: Callable[[HookContext, Exception], None],
+    ):
+        self.before = before
+        self.after = after
+        self.on_finally = on_finally
+        self.error = error

devcycle_python_sdk/models/eval_hook_context.py

@@ -0,0 +1,10 @@
+from typing import Any
+
+from devcycle_python_sdk.models.user import DevCycleUser
+
+
+class HookContext:
+    def __init__(self, key: str, user: DevCycleUser, default_value: Any):
+        self.key = key
+        self.default_value = default_value
+        self.user = user

devcycle_python_sdk/models/eval_reason.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+class EvalReasons:
+    """Evaluation reasons constants"""
+
+    DEFAULT = "DEFAULT"
+
+
+class DefaultReasonDetails:
+    """Default reason details constants"""
+
+    MISSING_CONFIG = "Missing Config"
+    USER_NOT_TARGETED = "User Not Targeted"
+    TYPE_MISMATCH = "Variable Type Mismatch"
+    MISSING_VARIABLE = "Missing Variable"
+    ERROR = "Error"
+
+
+@dataclass(order=False)
+class EvalReason:
+    reason: str
+    details: Optional[str] = None
+    target_id: Optional[str] = None
+
+    def to_json(self):
+        return {
+            key: getattr(self, key)
+            for key in self.__dataclass_fields__
+            if getattr(self, key) is not None
+        }
+
+    @classmethod
+    def from_json(cls, data: dict) -> "EvalReason":
+        return cls(
+            reason=data["reason"],
+            details=data.get("details"),
+            target_id=data.get("target_id"),
+        )

devcycle_python_sdk/models/user.py

@@ -101,22 +101,33 @@ class DevCycleUser:
     ) -> "DevCycleUser":
         """
         Builds a DevCycleUser instance from the evaluation context. Will raise a TargetingKeyMissingError if
-        the context does not contain a valid targeting key or user_id attribute
+        the context does not contain a valid targeting key, user_id, or userId attribute
 
         :param context: The evaluation context to build the user from
         :return: A DevCycleUser instance
         """
         user_id = None
+        user_id_source = None
 
         if context:
             if context.targeting_key:
                 user_id = context.targeting_key
+                user_id_source = "targeting_key"
             elif context.attributes and "user_id" in context.attributes.keys():
                 user_id = context.attributes["user_id"]
+                user_id_source = "user_id"
+            elif context.attributes and "userId" in context.attributes.keys():
+                user_id = context.attributes["userId"]
+                user_id_source = "userId"
 
-        if not user_id or not isinstance(user_id, str):
+        if not user_id:
             raise TargetingKeyMissingError(
-                "DevCycle: Evaluation context does not contain a valid targeting key or user_id attribute"
+                "DevCycle: Evaluation context does not contain a valid targeting key, user_id, or userId attribute"
+            )
+
+        if not isinstance(user_id, str):
+            raise TargetingKeyMissingError(
+                f"DevCycle: {user_id_source} must be a string, got {type(user_id).__name__}"
             )
 
         user = DevCycleUser(user_id=user_id)
@@ -124,7 +135,8 @@ class DevCycleUser:
         private_custom_data: Dict[str, Any] = {}
         if context and context.attributes:
             for key, value in context.attributes.items():
-                if key == "user_id":
+                # Skip user_id, userId, and targeting_key - these are reserved for user ID mapping
+                if key in ("user_id", "userId", "targeting_key"):
                     continue
 
                 if value is not None:

devcycle_python_sdk/models/variable.py

@@ -2,6 +2,8 @@
 from dataclasses import dataclass
 from typing import Optional, Any
 
+from .eval_reason import EvalReason, EvalReasons
+
 
 class TypeEnum:
     BOOLEAN = "Boolean"
@@ -32,16 +34,26 @@ class Variable:
     isDefaulted: Optional[bool] = False
     defaultValue: Any = None
     evalReason: Optional[str] = None
+    eval: Optional[EvalReason] = None
 
     def to_json(self):
-        return {
-            key: getattr(self, key)
-            for key in self.__dataclass_fields__
-            if getattr(self, key) is not None
-        }
+        result = {}
+        for key in self.__dataclass_fields__:
+            value = getattr(self, key)
+            if value is not None:
+                if key == "eval" and isinstance(value, EvalReason):
+                    result[key] = value.to_json()
+                else:
+                    result[key] = value
+        return result
 
     @classmethod
     def from_json(cls, data: dict) -> "Variable":
+        eval_data = data.get("eval")
+        eval_reason = None
+        if eval_data:
+            eval_reason = EvalReason.from_json(eval_data)
+
         return cls(
             _id=data["_id"],
             key=data["key"],
@@ -50,11 +62,20 @@ class Variable:
             isDefaulted=data.get("isDefaulted", None),
             defaultValue=data.get("defaultValue"),
             evalReason=data.get("evalReason"),
+            eval=eval_reason,
         )
 
     @staticmethod
-    def create_default_variable(key: str, default_value: Any) -> "Variable":
+    def create_default_variable(
+        key: str, default_value: Any, default_reason_detail: Optional[str] = None
+    ) -> "Variable":
         var_type = determine_variable_type(default_value)
+        if default_reason_detail is not None:
+            eval_reason = EvalReason(
+                reason=EvalReasons.DEFAULT, details=default_reason_detail
+            )
+        else:
+            eval_reason = None
         return Variable(
             _id=None,
             key=key,
@@ -62,4 +83,21 @@ class Variable:
             value=default_value,
             defaultValue=default_value,
             isDefaulted=True,
+            eval=eval_reason,
         )
+
+    def get_flag_meta_data(self) -> dict:
+        """
+        Returns metadata dictionary for OpenFeature flag resolution.
+
+        Returns:
+            dict: Dictionary containing evalReasonDetails and evalReasonTargetId
+                  if they exist, empty dict otherwise.
+        """
+        meta_data = {}
+        if self.eval:
+            if self.eval.details:
+                meta_data["evalReasonDetails"] = self.eval.details
+            if self.eval.target_id:
+                meta_data["evalReasonTargetId"] = self.eval.target_id
+        return meta_data

devcycle_python_sdk/open_feature_provider/provider.py

@@ -80,13 +80,18 @@ class DevCycleProvider(AbstractProvider):
                         reason=Reason.DEFAULT,
                     )
                 else:
+                    # TODO: once eval enabled from cloud bucketing, eval reason won't be null unless defaulted
+                    if variable.eval and variable.eval.reason:
+                        reason = variable.eval.reason
+                    elif variable.isDefaulted:
+                        reason = Reason.DEFAULT
+                    else:
+                        reason = Reason.TARGETING_MATCH
+
                     return FlagResolutionDetails(
                         value=variable.value,
-                        reason=(
-                            Reason.DEFAULT
-                            if variable.isDefaulted
-                            else Reason.TARGETING_MATCH
-                        ),
+                        reason=reason,
+                        flag_metadata=variable.get_flag_meta_data(),
                     )
             except ValueError as e:
                 # occurs if the key or default value is None

devcycle_python_sdk/options.py

@@ -1,5 +1,7 @@
 import logging
-from typing import Callable, Optional, Dict, Any
+from typing import Callable, Optional, Dict, Any, List
+
+from devcycle_python_sdk.models.eval_hook import EvalHook
 
 logger = logging.getLogger(__name__)
 
@@ -16,12 +18,14 @@ class DevCycleCloudOptions:
         request_timeout: int = 5,  # seconds
         request_retries: int = 5,
         retry_delay: int = 200,  # milliseconds
+        eval_hooks: Optional[List[EvalHook]] = None,
     ):
         self.enable_edge_db = enable_edge_db
         self.bucketing_api_uri = bucketing_api_uri
         self.request_timeout = request_timeout
         self.request_retries = request_retries
         self.retry_delay = retry_delay
+        self.eval_hooks = eval_hooks if eval_hooks is not None else []
 
 
 class DevCycleLocalOptions:
@@ -47,6 +51,7 @@ class DevCycleLocalOptions:
         disable_custom_event_logging: bool = False,
         enable_beta_realtime_updates: bool = False,
         disable_realtime_updates: bool = False,
+        eval_hooks: Optional[List[EvalHook]] = None,
     ):
         self.events_api_uri = events_api_uri
         self.config_cdn_uri = config_cdn_uri
@@ -69,6 +74,8 @@ class DevCycleLocalOptions:
                 "DevCycle: `enable_beta_realtime_updates` is deprecated and will be removed in a future release.",
             )
 
+        self.eval_hooks = eval_hooks if eval_hooks is not None else []
+
         if self.flush_event_queue_size >= self.max_event_queue_size:
             logger.warning(
                 f"DevCycle: flush_event_queue_size: {self.flush_event_queue_size} must be smaller than max_event_queue_size: {self.max_event_queue_size}"