devcycle-python-server-sdk 3.11.4__py3-none-any.whl → 3.13.0__py3-none-any.whl

devcycle_python_sdk/VERSION.txt

@@ -1 +1 @@
-3.11.4
+3.13.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

@@ -5,7 +5,7 @@ import json
 
 from pathlib import Path
 from threading import Lock
-from typing import Any, cast, Optional, List
+from typing import Any, cast, Optional, List, Tuple
 
 import wasmtime
 from wasmtime import (
@@ -22,13 +22,13 @@ 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
 from devcycle_python_sdk.models.user import DevCycleUser
 from devcycle_python_sdk.models.variable import Variable, determine_variable_type
 from devcycle_python_sdk.models.event import FlushPayload
+from devcycle_python_sdk.models.config_metadata import ConfigMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -141,6 +141,7 @@ class LocalBucketing:
             "generateBucketedConfigForUserUTF8"
         )
         self.VariableForUserProtobuf = self._get_export("variableForUser_PB")
+        self.getConfigMetadata = self._get_export("getConfigMetadata")
 
         # Extract variable type enum values from WASM
         self.variable_type_map = {
@@ -299,7 +300,7 @@ class LocalBucketing:
 
     def get_variable_for_user_protobuf(
         self, user: DevCycleUser, key: str, default_value: Any
-    ) -> Optional[Variable]:
+    ) -> Tuple[Optional[Variable], Optional[str]]:
         var_type = determine_variable_type(default_value)
         pb_variable_type = pb_utils.convert_type_enum_to_variable_type(var_type)
 
@@ -318,20 +319,18 @@ class LocalBucketing:
             variable_addr = self.VariableForUserProtobuf(self.wasm_store, params_addr)
 
             if variable_addr == 0:
-                return None
+                return None, None
             else:
                 var_bytes = self._read_assembly_script_byte_array(variable_addr)
                 sdk_variable = pb2.SDKVariable_PB()
                 sdk_variable.ParseFromString(var_bytes)
+                feature_id = (
+                    sdk_variable._feature.value
+                    if sdk_variable._feature.value is not None
+                    else None
+                )
 
-                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)
+                return pb_utils.create_variable(sdk_variable, default_value), feature_id
 
     def generate_bucketed_config(self, user: DevCycleUser) -> BucketedConfig:
         user_json = json.dumps(user.to_json())
@@ -365,6 +364,14 @@ class LocalBucketing:
             config_addr = self._new_assembly_script_byte_array(data)
             self.setConfigDataUTF8(self.wasm_store, self.sdk_key_addr, config_addr)
 
+    def get_config_metadata(self) -> Optional[ConfigMetadata]:
+        with self.wasm_lock:
+            config_addr = self.getConfigMetadata(self.wasm_store, self.sdk_key_addr)
+            config_bytes = self._read_assembly_script_string(config_addr)
+            config_data = json.loads(config_bytes.encode("utf-8"))
+
+            return ConfigMetadata.from_json(config_data)
+
     def set_platform_data(self, platform_json: str) -> None:
         with self.wasm_lock:
             data = platform_json.encode("utf-8")

devcycle_python_sdk/cloud_client.py

@@ -14,6 +14,9 @@ from devcycle_python_sdk.managers.eval_hooks_manager import (
     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
@@ -112,7 +115,7 @@ class DevCycleCloudClient(AbstractDevCycleClient):
                 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)
+                self.eval_hooks_manager.run_after(context, variable, None)
             else:
                 raise before_hook_error
         except CloudClientUnauthorizedError as e:
@@ -121,7 +124,9 @@ class DevCycleCloudClient(AbstractDevCycleClient):
         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.ERROR,
             )
         except BeforeHookError as e:
             self.eval_hooks_manager.run_error(context, e)
@@ -130,10 +135,12 @@ class DevCycleCloudClient(AbstractDevCycleClient):
         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)
+            self.eval_hooks_manager.run_finally(context, variable, None)
 
         variable.defaultValue = default_value
 
@@ -143,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

devcycle_python_sdk/local_client.py

@@ -6,7 +6,6 @@ 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,
@@ -17,11 +16,17 @@ 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
 from devcycle_python_sdk.models.user import DevCycleUser
 from devcycle_python_sdk.models.variable import Variable
+from devcycle_python_sdk.models.variable_metadata import VariableMetadata
 from devcycle_python_sdk.open_feature_provider.provider import DevCycleProvider
 from openfeature.provider import AbstractProvider
 
@@ -131,7 +136,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,
                 )
@@ -139,9 +147,14 @@ 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)
+        config_metadata = self.local_bucketing.get_config_metadata()
+        variable_metadata = None
+
+        context = HookContext(key, user, default_value, config_metadata)
         variable = Variable.create_default_variable(
             key=key, default_value=default_value
         )
@@ -154,30 +167,40 @@ class DevCycleLocalClient(AbstractDevCycleClient):
                     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
+            bucketed_variable, feature_id = (
+                self.local_bucketing.get_variable_for_user_protobuf(
+                    user, key, default_value
+                )
             )
+            if feature_id is not None:
+                variable_metadata = VariableMetadata(feature_id=feature_id)
             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)
+                self.eval_hooks_manager.run_after(context, variable, variable_metadata)
             else:
                 raise before_hook_error
-        except VariableTypeMismatchError:
-            logger.debug("DevCycle: Variable type mismatch, returning default value")
-            return variable
-        except BeforeHookError as e:
-            self.eval_hooks_manager.run_error(context, e)
-            return variable
-        except AfterHookError as e:
-            self.eval_hooks_manager.run_error(context, e)
-            return variable
         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
         finally:
-            self.eval_hooks_manager.run_finally(context, variable)
+            self.eval_hooks_manager.run_finally(context, variable, variable_metadata)
         return variable
 
     def _generate_bucketed_config(self, user: DevCycleUser) -> BucketedConfig:

devcycle_python_sdk/managers/config_manager.py

@@ -16,6 +16,7 @@ from devcycle_python_sdk.exceptions import (
 from wsgiref.handlers import format_date_time
 from devcycle_python_sdk.options import DevCycleLocalOptions
 from devcycle_python_sdk.managers.sse_manager import SSEManager
+from devcycle_python_sdk.models.config_metadata import ConfigMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -108,6 +109,9 @@ class EnvironmentConfigManager(threading.Thread):
             )
             self._polling_enabled = False
 
+    def get_config_metadata(self) -> Optional[ConfigMetadata]:
+        return self._local_bucketing.get_config_metadata()
+
     def run(self):
         while self._polling_enabled:
             try:

devcycle_python_sdk/managers/eval_hooks_manager.py

@@ -3,6 +3,7 @@ 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.models.variable_metadata import VariableMetadata
 from devcycle_python_sdk.options import logger
 
 
@@ -48,19 +49,29 @@ class EvalHooksManager:
                 raise BeforeHookError(f"Before hook failed: {e}", e)
         return modified_context
 
-    def run_after(self, context: HookContext, variable: Variable) -> None:
+    def run_after(
+        self,
+        context: HookContext,
+        variable: Variable,
+        variable_metadata: Optional[VariableMetadata],
+    ) -> None:
         """Run after hooks with the evaluation result"""
         for hook in self.hooks:
             try:
-                hook.after(context, variable)
+                hook.after(context, variable, variable_metadata)
             except Exception as e:
                 raise AfterHookError(f"After hook failed: {e}", e)
 
-    def run_finally(self, context: HookContext, variable: Optional[Variable]) -> None:
+    def run_finally(
+        self,
+        context: HookContext,
+        variable: Optional[Variable],
+        variable_metadata: Optional[VariableMetadata],
+    ) -> None:
         """Run finally hooks after evaluation completes"""
         for hook in self.hooks:
             try:
-                hook.on_finally(context, variable)
+                hook.on_finally(context, variable, variable_metadata)
             except Exception as e:
                 logger.error(f"Error running finally hook: {e}")
 

devcycle_python_sdk/managers/event_queue_manager.py

@@ -19,7 +19,6 @@ from devcycle_python_sdk.models.event import (
 from devcycle_python_sdk.models.user import DevCycleUser
 from devcycle_python_sdk.models.bucketed_config import BucketedConfig
 
-
 logger = logging.getLogger(__name__)
 
 

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/config_metadata.py

@@ -0,0 +1,40 @@
+from devcycle_python_sdk.models.environment_metadata import EnvironmentMetadata
+from devcycle_python_sdk.models.project_metadata import ProjectMetadata
+from typing import Dict, Any, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class ConfigMetadata:
+    project: ProjectMetadata
+    environment: EnvironmentMetadata
+
+    def to_json(self):
+        result = {}
+        for field_name in self.__dataclass_fields__:
+            value = getattr(self, field_name)
+            if value is not None:
+                if field_name == "project" and isinstance(value, ProjectMetadata):
+                    result[field_name] = value.to_json()
+                elif field_name == "environment" and isinstance(
+                    value, EnvironmentMetadata
+                ):
+                    result[field_name] = value.to_json()
+                else:
+                    result[field_name] = value
+        return result
+
+    @staticmethod
+    def from_json(json_obj: Optional[Dict[str, Any]]) -> Optional["ConfigMetadata"]:
+        if json_obj is None:
+            return None
+        project = ProjectMetadata.from_json(json_obj.get("project"))
+        environment = EnvironmentMetadata.from_json(json_obj.get("environment"))
+
+        if project is None or environment is None:
+            return None
+
+        return ConfigMetadata(
+            project=project,
+            environment=environment,
+        )

devcycle_python_sdk/models/environment_metadata.py

@@ -0,0 +1,26 @@
+from typing import Dict, Any, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class EnvironmentMetadata:
+    id: str
+    key: str
+
+    @staticmethod
+    def from_json(
+        json_obj: Optional[Dict[str, Any]],
+    ) -> Optional["EnvironmentMetadata"]:
+        if json_obj is None:
+            return None
+        return EnvironmentMetadata(
+            id=json_obj["id"],
+            key=json_obj["key"],
+        )
+
+    def to_json(self):
+        result = {}
+        for field_name in self.__dataclass_fields__:
+            value = getattr(self, field_name)
+            result[field_name] = value
+        return result

devcycle_python_sdk/models/eval_hook.py

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

devcycle_python_sdk/models/eval_hook_context.py

@@ -1,10 +1,28 @@
-from typing import Any
+from typing import Any, Optional
+from dataclasses import dataclass
 
 from devcycle_python_sdk.models.user import DevCycleUser
+from devcycle_python_sdk.models.config_metadata import ConfigMetadata
 
 
+@dataclass
 class HookContext:
-    def __init__(self, key: str, user: DevCycleUser, default_value: Any):
-        self.key = key
-        self.default_value = default_value
-        self.user = user
+    key: str
+    user: DevCycleUser
+    default_value: Any
+    config_metadata: Optional[ConfigMetadata] = None
+
+    def to_json(self):
+        result = {}
+        for field_name in self.__dataclass_fields__:
+            value = getattr(self, field_name)
+            if value is not None:
+                if field_name == "config_metadata" and isinstance(
+                    value, ConfigMetadata
+                ):
+                    result[field_name] = value.to_json()
+                elif field_name == "user" and isinstance(value, DevCycleUser):
+                    result[field_name] = value.to_json()
+                else:
+                    result[field_name] = value
+        return result

devcycle_python_sdk/models/eval_reason.py

@@ -0,0 +1,39 @@
+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"
+    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/project_metadata.py

@@ -0,0 +1,24 @@
+from typing import Dict, Any, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class ProjectMetadata:
+    id: str
+    key: str
+
+    @staticmethod
+    def from_json(json_obj: Optional[Dict[str, Any]]) -> Optional["ProjectMetadata"]:
+        if json_obj is None:
+            return None
+        return ProjectMetadata(
+            id=json_obj["id"],
+            key=json_obj["key"],
+        )
+
+    def to_json(self):
+        result = {}
+        for field_name in self.__dataclass_fields__:
+            value = getattr(self, field_name)
+            result[field_name] = value
+        return result

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/models/variable_metadata.py

@@ -0,0 +1,22 @@
+from typing import Dict, Any, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class VariableMetadata:
+    feature_id: str
+
+    @staticmethod
+    def from_json(json_obj: Optional[Dict[str, Any]]) -> Optional["VariableMetadata"]:
+        if json_obj is None:
+            return None
+        return VariableMetadata(
+            feature_id=json_obj["feature_id"],
+        )
+
+    def to_json(self):
+        result = {}
+        for field_name in self.__dataclass_fields__:
+            value = getattr(self, field_name)
+            result[field_name] = value
+        return result