devcycle-python-server-sdk 2.0.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

devcycle_python_sdk/local_client.py

@@ -0,0 +1,220 @@
+import json
+import logging
+from numbers import Real
+from typing import Any, Dict, Union
+
+from devcycle_python_sdk import DevCycleLocalOptions
+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.event_queue_manager import EventQueueManager
+from devcycle_python_sdk.models.bucketed_config import BucketedConfig
+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
+
+logger = logging.getLogger(__name__)
+
+
+class DevCycleLocalClient:
+    def __init__(self, sdk_key: str, options: DevCycleLocalOptions):
+        _validate_sdk_key(sdk_key)
+        self._sdk_key = sdk_key
+
+        if options is None:
+            self.options: DevCycleLocalOptions = DevCycleLocalOptions()
+        else:
+            self.options = options
+
+        self.local_bucketing = LocalBucketing(sdk_key)
+
+        self._platform_data = default_platform_data()
+        self.local_bucketing.set_platform_data(
+            json.dumps(self._platform_data.to_json())
+        )
+
+        self.config_manager: EnvironmentConfigManager = EnvironmentConfigManager(
+            sdk_key, self.options, self.local_bucketing
+        )
+        self.event_queue_manager: EventQueueManager = EventQueueManager(
+            sdk_key, self.options, self.local_bucketing
+        )
+
+    def is_initialized(self) -> bool:
+        return self.config_manager.is_initialized()
+
+    def set_client_custom_data(
+        self, custom_data: Dict[str, Union[str, Real, bool, None]]
+    ) -> None:
+        """
+        Sets global custom data for this client. This data will be utilized in all segmentation and bucketing
+        decisions. This data will be merged with any custom data set on the user object, with user data
+        taking priority
+
+        :param custom_data: Global data to set.  Supported values are strings, numbers, booleans. Nested dictionaries
+        are not permitted
+        """
+        if not self.is_initialized():
+            logger.debug("set_client_custom_data called before client has initialized")
+            return
+
+        if custom_data:
+            try:
+                custom_data_json = json.dumps(custom_data)
+                self.local_bucketing.set_client_custom_data(custom_data_json)
+            except Exception as e:
+                logger.error("Error setting custom data: " + str(e))
+
+    def variable_value(self, user: DevCycleUser, key: str, default_value: Any) -> Any:
+        """
+        Evaluates a variable for a user and returns the value.  If the user is not bucketed into the variable, the default value will be returned
+
+        :param user: The user to evaluate the variable for
+        """
+        return self.variable(user, key, default_value).value
+
+    def variable(self, user: DevCycleUser, key: str, default_value: Any) -> Variable:
+        """
+        Evaluates a variable for a user.
+
+        :param user: The user to evaluate the variable for
+        :param key: The key of the variable to evaluate
+        :param default_value: The default value to return if the user is not bucketed into the variable
+        """
+        _validate_user(user)
+
+        if not key:
+            raise ValueError("Missing parameter: key")
+
+        if default_value is None:
+            raise ValueError("Missing parameter: defaultValue")
+
+        if not self.is_initialized():
+            logger.debug("variable called before client has initialized")
+            try:
+                self.event_queue_manager.queue_aggregate_event(
+                    event=DevCycleEvent(
+                        type=EventType.AggVariableDefaulted, target=key, value=1
+                    ),
+                    bucketed_config=None,
+                )
+            except Exception as e:
+                logger.warning(
+                    f"Unable to track AggVariableDefaulted event for Variable {key}: {e}"
+                )
+            return Variable.create_default_variable(key, default_value)
+
+        try:
+            variable = self.local_bucketing.get_variable_for_user_protobuf(
+                user, key, default_value
+            )
+            if variable:
+                return variable
+        except VariableTypeMismatchError:
+            logger.debug("Variable type mismatch, returning default value")
+        except Exception as e:
+            logger.warning(f"Error retrieving variable for user: {e}")
+
+        return Variable.create_default_variable(key, default_value)
+
+    def _generate_bucketed_config(self, user: DevCycleUser) -> BucketedConfig:
+        """
+        Generates a bucketed config for a user.  This method will return an empty config if the client has not been initialized or if the user is not bucketed into any features or variables
+        """
+
+        _validate_user(user)
+
+        return self.local_bucketing.generate_bucketed_config(user)
+
+    def all_variables(self, user: DevCycleUser) -> Dict[str, Variable]:
+        """
+        Returns all segmented and bucketed variables 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 variables
+
+        :param user: The user to retrieve variables for
+        """
+        _validate_user(user)
+
+        if not self.is_initialized():
+            logger.warning("all_variables called before client has initialized")
+            return {}
+
+        variable_map: Dict[str, Variable] = {}
+
+        try:
+            return self.local_bucketing.generate_bucketed_config(user).variables
+        except Exception as e:
+            logger.exception(f"Error retrieving all variables for a user: {e}")
+            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
+
+        :param user: The user to retrieve features for
+        """
+        _validate_user(user)
+
+        if not self.is_initialized():
+            logger.warning("all_features called before client has initialized")
+            return {}
+
+        feature_map: Dict[str, Feature] = {}
+        try:
+            return self.local_bucketing.generate_bucketed_config(user).features
+        except Exception as e:
+            logger.exception(f"Error retrieving all features for a user: {e}")
+
+        return feature_map
+
+    def track(self, user: DevCycleUser, user_event: DevCycleEvent) -> None:
+        """
+        Tracks a custom event for a user.  This method will return immediately and the event will be queued for processing in the background.  If the client has not been initialized, this method will return immediately and the event will be discarded.
+
+        :param user: The user to track the event for
+        :param user_event: The event to track
+        """
+        _validate_user(user)
+
+        if user_event is None:
+            raise ValueError("Invalid Event")
+
+        if user_event.type is None or len(user_event.type) == 0:
+            raise ValueError("Missing parameter: type")
+
+        if not self.is_initialized():
+            logger.debug("track called before client has initialized")
+            return
+
+        try:
+            self.event_queue_manager.queue_event(user, user_event)
+        except Exception as e:
+            logger.error(f"Error tracking event: {e}")
+
+    def close(self) -> None:
+        """
+        Closes the client and releases any resources held by it.
+        """
+        self.config_manager.close()
+        self.event_queue_manager.close()
+
+
+def _validate_sdk_key(sdk_key: str) -> None:
+    if sdk_key is None or len(sdk_key) == 0:
+        raise ValueError("Missing SDK key! Call initialize with a valid SDK key")
+
+    if not sdk_key.startswith("server") and not sdk_key.startswith("dvc_server"):
+        raise ValueError(
+            "Invalid SDK key provided. Please call initialize with a valid server SDK key"
+        )
+
+
+def _validate_user(user: DevCycleUser) -> None:
+    if user is None:
+        raise ValueError("User cannot be None")
+
+    if user.user_id is None or len(user.user_id) == 0:
+        raise ValueError("userId cannot be empty")

devcycle_python_sdk/managers/config_manager.py

@@ -0,0 +1,95 @@
+import threading
+import time
+import logging
+import json
+from typing import Optional
+
+from devcycle_python_sdk.options import DevCycleLocalOptions
+from devcycle_python_sdk.api.local_bucketing import LocalBucketing
+from devcycle_python_sdk.api.config_client import ConfigAPIClient
+from devcycle_python_sdk.exceptions import (
+    CloudClientUnauthorizedError,
+    CloudClientError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class EnvironmentConfigManager(threading.Thread):
+    def __init__(
+        self,
+        sdk_key: str,
+        options: DevCycleLocalOptions,
+        local_bucketing: LocalBucketing,
+    ):
+        super().__init__()
+
+        self._sdk_key = sdk_key
+        self._options = options
+        self._local_bucketing = local_bucketing
+
+        self._config: Optional[dict] = None
+        self._config_etag: Optional[str] = None
+
+        self._config_api_client = ConfigAPIClient(self._sdk_key, self._options)
+
+        self._polling_enabled = True
+        self.daemon = True
+        self.start()
+
+    def is_initialized(self) -> bool:
+        return self._config is not None
+
+    def _get_config(self):
+        try:
+            new_config, new_etag = self._config_api_client.get_config(
+                config_etag=self._config_etag
+            )
+
+            if new_config is None and new_etag == self._config_etag:
+                # api not returning data and the etag is the same
+                # no change to the config since last request
+                return
+            elif new_config is None:
+                logger.warning(
+                    "Config CDN fetch returned no data with a different etag"
+                )
+                return
+
+            trigger_on_client_initialized = self._config is None
+
+            self._config = new_config
+            self._config_etag = new_etag
+
+            json_config = json.dumps(self._config)
+            self._local_bucketing.store_config(json_config)
+
+            if (
+                trigger_on_client_initialized
+                and self._options.on_client_initialized is not None
+            ):
+                try:
+                    self._options.on_client_initialized()
+                except Exception as e:
+                    # consume any error
+                    logger.warning(
+                        f"Error received from on_client_initialized callback: {str(e)}"
+                    )
+        except CloudClientError as e:
+            logger.warning(f"Config fetch failed. Status: {str(e)}")
+        except CloudClientUnauthorizedError:
+            logger.error("Unauthorized to get config. Aborting config polling.")
+            self._polling_enabled = False
+
+    def run(self):
+        while self._polling_enabled:
+            try:
+                self._get_config()
+            except Exception as e:
+                if self._polling_enabled:
+                    # Only log a warning if we're still polling
+                    logger.warning(f"Error polling for config changes: {str(e)}")
+            time.sleep(self._options.config_polling_interval_ms / 1000.0)
+
+    def close(self):
+        self._polling_enabled = False

devcycle_python_sdk/managers/event_queue_manager.py

@@ -0,0 +1,223 @@
+import threading
+import logging
+import json
+from typing import Optional
+
+from devcycle_python_sdk.options import DevCycleLocalOptions
+from devcycle_python_sdk.api.local_bucketing import LocalBucketing
+from devcycle_python_sdk.api.event_client import EventAPIClient
+from devcycle_python_sdk.exceptions import (
+    APIClientError,
+    APIClientUnauthorizedError,
+    NotFoundError,
+)
+from devcycle_python_sdk.models.event import (
+    FlushPayload,
+    DevCycleEvent,
+    EventType,
+)
+from devcycle_python_sdk.models.user import DevCycleUser
+from devcycle_python_sdk.models.bucketed_config import BucketedConfig
+
+
+logger = logging.getLogger(__name__)
+
+
+class QueueFullError(Exception):
+    pass
+
+
+class EventQueueManager(threading.Thread):
+    def __init__(
+        self,
+        sdk_key: str,
+        options: DevCycleLocalOptions,
+        local_bucketing: LocalBucketing,
+    ):
+        super().__init__()
+
+        if sdk_key is None or sdk_key == "":
+            raise ValueError("DevCycle is not yet initialized to publish events.")
+
+        self._sdk_key = sdk_key
+        self._options = options
+        self._local_bucketing = local_bucketing
+        self._event_api_client = EventAPIClient(self._sdk_key, self._options)
+        self._flush_lock = threading.Lock()
+        self._exit = threading.Event()
+        self._exited = threading.Event()
+
+        # Setup the event queue inside the WASM module
+        event_options_json = json.dumps(self._options.event_queue_options())
+        self._local_bucketing.init_event_queue(event_options_json)
+
+        # Only start event processing thread if event logging is enabled
+        if not (
+            self._options.disable_custom_event_logging
+            and self._options.disable_automatic_event_logging
+        ):
+            self.daemon = True
+            self.start()
+        else:
+            self._stop_running()
+            self._mark_exited()
+
+    def _should_run(self) -> bool:
+        # Returns true if the thread should continue running, false otherwise
+        return not self._exit.is_set()
+
+    def _stop_running(self) -> None:
+        # Indicate to the thread that it should stop running, interrupting any sleep
+        self._exit.set()
+
+    def _sleep(self) -> bool:
+        # Returns true if the sleep was interrupted, false otherwise
+        return self._exit.wait(self._options.event_flush_interval_ms / 1000.0)
+
+    def _mark_exited(self) -> None:
+        # Indicate to the thread calling close that the thread has exited
+        self._exited.set()
+
+    def _wait_for_exit(self, timeout_seconds: float) -> bool:
+        # Wait up to timeout_seconds for the thread to exit
+        # This works whether the thread was actually started or not
+        return self._exited.wait(timeout_seconds)
+
+    def _flush_events(self) -> int:
+        if self._flush_lock.locked():
+            return 0
+
+        with self._flush_lock:
+            try:
+                payloads = self._local_bucketing.flush_event_queue()
+            except Exception as e:
+                logger.error(f"Error flushing event payloads: {str(e)}")
+
+            event_count = 0
+            if payloads:
+                logger.debug(f"Flush {len(payloads)} event payloads")
+                for payload in payloads:
+                    event_count += payload.eventCount
+                    self._publish_event_payload(payload)
+                logger.debug(f"Flush {event_count} events, for {len(payloads)} users")
+            return event_count
+
+    def _publish_event_payload(self, payload: FlushPayload) -> None:
+        if payload and payload.records:
+            try:
+                self._event_api_client.publish_events(payload.records)
+                self._local_bucketing.on_event_payload_success(payload.payloadId)
+            except APIClientUnauthorizedError:
+                logger.error(
+                    "Unauthorized to publish events, please check your SDK key"
+                )
+                # stop the thread
+                self._stop_running()
+                self._local_bucketing.on_event_payload_failure(payload.payloadId, False)
+            except NotFoundError as e:
+                logger.error(
+                    f"Unable to reach the DevCycle Events API service: {str(e)}"
+                )
+                self._stop_running()
+                self._local_bucketing.on_event_payload_failure(payload.payloadId, False)
+            except APIClientError as e:
+                logger.warning(
+                    f"Error publishing events to DevCycle Events API service: {str(e)}"
+                )
+                self._local_bucketing.on_event_payload_failure(payload.payloadId, True)
+
+    def is_event_logging_disabled(self, event_type: str) -> bool:
+        if event_type in [
+            EventType.VariableDefaulted,
+            EventType.VariableEvaluated,
+            EventType.AggVariableDefaulted,
+            EventType.AggVariableEvaluated,
+        ]:
+            return self._options.disable_automatic_event_logging
+        else:
+            return self._options.disable_custom_event_logging
+
+    def run(self):
+        while self._should_run():
+            try:
+                self._flush_events()
+            except Exception as e:
+                logger.warning(f"Error flushing events: {str(e)}")
+
+            self._sleep()
+
+        self._mark_exited()
+
+    def close(self):
+        self._stop_running()
+
+        # Wait up to 1s for the thread to exit.
+        # Because the sleeping between batches is interruptible, this is only
+        # providing time for an in-flight batch to finish.
+        if not self._wait_for_exit(1.0):
+            logger.error("Timed out waiting for event flushing thread to stop")
+
+        try:
+            self._flush_events()
+        except Exception as e:
+            logger.warning(f"DVC Error flushing events when closing client: {str(e)}")
+
+    def queue_event(self, user: DevCycleUser, event: DevCycleEvent) -> None:
+        if user is None:
+            raise ValueError("user cannot be None")
+
+        if event is None:
+            raise ValueError("event cannot be None")
+
+        if not event.type:
+            raise ValueError("event type not set")
+
+        try:
+            self._check_queue_status()
+        except QueueFullError:
+            logger.warning("Event queue is full, dropping user event")
+            return
+
+        user_json = json.dumps(user.to_json())
+        event_json = json.dumps(event.to_json())
+        self._local_bucketing.queue_event(user_json, event_json)
+
+    def queue_aggregate_event(
+        self, event: DevCycleEvent, bucketed_config: Optional[BucketedConfig]
+    ) -> None:
+        if event is None:
+            raise ValueError("event cannot be None")
+
+        if not event.type:
+            raise ValueError("event type not set")
+
+        if not event.target:
+            raise ValueError("event target not set")
+
+        try:
+            self._check_queue_status()
+        except QueueFullError:
+            logger.warning("Event queue is full, dropping aggregate event")
+            return
+
+        event_json = json.dumps(event.to_json())
+        if bucketed_config and bucketed_config.variable_variation_map:
+            variation_map_json = json.dumps(bucketed_config.variable_variation_map)
+        else:
+            variation_map_json = "{}"
+        self._local_bucketing.queue_aggregate_event(event_json, variation_map_json)
+
+    def _check_queue_status(self) -> None:
+        if self._flush_needed():
+            self._flush_events()
+
+        if self._queue_full():
+            raise QueueFullError()
+
+    def _flush_needed(self) -> bool:
+        queue_size = self._local_bucketing.get_event_queue_size()
+        return queue_size >= self._options.flush_event_queue_size
+
+    def _queue_full(self) -> bool:
+        queue_size = self._local_bucketing.get_event_queue_size()
+        return queue_size >= self._options.max_event_queue_size

devcycle_python_sdk/models/bucketed_config.py

@@ -0,0 +1,150 @@
+# ruff: noqa: N815
+from dataclasses import dataclass
+from typing import Dict, List
+from typing import Optional
+
+from .user import DevCycleUser
+from .variable import Variable
+from .feature import Feature
+
+
+@dataclass
+class EdgeDBSettings:
+    enabled: bool
+
+    @classmethod
+    def from_json(cls, data: dict) -> "EdgeDBSettings":
+        return cls(
+            enabled=data.get("enabled", False),
+        )
+
+
+@dataclass
+class OptInColors:
+    primary: str
+    secondary: str
+
+    @classmethod
+    def from_json(cls, data: dict) -> "OptInColors":
+        return cls(
+            primary=data.get("primary", ""),
+            secondary=data.get("secondary", ""),
+        )
+
+
+@dataclass
+class OptInSettings:
+    enabled: bool
+    title: str
+    description: str
+    image_url: str
+    colors: OptInColors
+
+    @classmethod
+    def from_json(cls, data: dict) -> "OptInSettings":
+        return cls(
+            enabled=data.get("enabled", False),
+            title=data.get("title", ""),
+            description=data.get("description", ""),
+            image_url=data.get("imageURL", ""),
+            colors=OptInColors.from_json(data.get("colors", "")),
+        )
+
+
+@dataclass
+class ProjectSettings:
+    edge_db: Optional[EdgeDBSettings]
+    opt_in: Optional[OptInSettings]
+
+    @classmethod
+    def from_json(cls, data: dict) -> "ProjectSettings":
+        return cls(
+            edge_db=EdgeDBSettings.from_json(data["edgeDB"])
+            if "edgeDB" in data
+            else None,
+            opt_in=OptInSettings.from_json(data["optIn"]) if "optIn" in data else None,
+        )
+
+
+@dataclass
+class Project:
+    id: str
+    key: str
+    a0_organization: str
+    settings: Optional[ProjectSettings]
+
+    @classmethod
+    def from_json(cls, data: dict) -> "Project":
+        return cls(
+            id=data["_id"],
+            key=data["key"],
+            a0_organization=data["a0_organization"],
+            settings=ProjectSettings.from_json(data["settings"])
+            if "settings" in data
+            else None,
+        )
+
+
+@dataclass
+class Environment:
+    id: str
+    key: str
+
+    @classmethod
+    def from_json(cls, data: dict) -> "Environment":
+        return cls(
+            id=data["_id"],
+            key=data["key"],
+        )
+
+
+@dataclass
+class FeatureVariation:
+    feature: str
+    variation: str
+
+    @classmethod
+    def from_json(cls, data: dict) -> "FeatureVariation":
+        return cls(
+            feature=data["_feature"],
+            variation=data["_variation"],
+        )
+
+
+@dataclass(order=False)
+class BucketedConfig:
+    project: Project
+    environment: Environment
+    features: Dict[str, Feature]
+    feature_variation_map: Dict[str, str]
+    variable_variation_map: Dict[str, FeatureVariation]
+    variables: Dict[str, Variable]
+    known_variable_keys: List[float]
+
+    user: Optional[DevCycleUser] = 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) -> "BucketedConfig":
+        return cls(
+            project=Project.from_json(data["project"]),
+            environment=Environment.from_json(data["environment"]),
+            features={
+                k: Feature.from_json(v) for k, v in data.get("features", {}).items()
+            },
+            feature_variation_map=data.get("featureVariationMap", {}),
+            variable_variation_map={
+                k: FeatureVariation.from_json(v)
+                for k, v in data.get("variableVariationMap", {}).items()
+            },
+            variables={
+                k: Variable.from_json(v) for k, v in data.get("variables", {}).items()
+            },
+            known_variable_keys=data.get("knownVariableKeys", []),
+        )