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

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", []),
+        )

devcycle_python_sdk/models/event.py

@@ -1,20 +1,123 @@
 # ruff: noqa: N815
 from dataclasses import dataclass, field
-from typing import Dict, Optional
-from time import time
+from typing import Dict, Optional, Any, List
+from datetime import datetime, timezone
+
+from .user import DevCycleUser
+
+
+class EventType:
+    VariableEvaluated = "variableEvaluated"
+    AggVariableEvaluated = "aggVariableEvaluated"
+    VariableDefaulted = "variableDefaulted"
+    AggVariableDefaulted = "aggVariableDefaulted"
+    CustomEvent = "customEvent"
 
 
 @dataclass(order=False)
-class Event:
+class DevCycleEvent:
     type: Optional[str] = None
     target: Optional[str] = None
-    date: int = field(default_factory=lambda: int(time()))
+    date: datetime = field(default_factory=lambda: datetime.utcnow())
     value: Optional[int] = None
-    metaData: Dict[str, str] = field(default_factory=dict)
+    metaData: Optional[Dict[str, str]] = None
 
-    def to_json(self):
-        return {
+    def to_json(self, use_bucketing_api_format: bool = False) -> Dict[str, Any]:
+        json_dict = {
             key: getattr(self, key)
             for key in self.__dataclass_fields__
-            if getattr(self, key) is not None
+            if getattr(self, key) is not None and key != "date"
         }
+        if self.date:
+            if use_bucketing_api_format:
+                # convert to timestamp in milliseconds as required by the bucketing API
+                json_dict["date"] = int(self.date.timestamp() * 1000)
+            else:
+                # convert to UTC and format as ISO string
+                json_dict["date"] = self.date.astimezone(tz=timezone.utc).isoformat()
+        return json_dict
+
+
+@dataclass(order=False)
+class RequestEvent:
+    """
+    An event generated by local bucketing event that can be sent to the Events API
+    Not interfaced by developers, purely for internal use
+    """
+
+    type: str
+    user_id: str
+    # will be a timestamp in iso format
+    clientDate: str
+    # will be a timestamp in iso format
+    date: str
+    target: Optional[str] = None
+    customType: Optional[str] = None
+    value: Optional[float] = 0
+    featureVars: Dict[str, str] = field(default_factory=dict)
+    metaData: Optional[Dict[str, str]] = None
+
+    def to_json(self):
+        json_obj = {}
+        for key in self.__dataclass_fields__:
+            json_obj[key] = getattr(self, key)
+
+        return json_obj
+
+    @classmethod
+    def from_json(cls, data: dict) -> "RequestEvent":
+        return cls(
+            type=data["type"],
+            user_id=data["user_id"],
+            clientDate=data["clientDate"],
+            date=data["date"],
+            target=data.get("target"),
+            customType=data.get("customType"),
+            value=data.get("value", 0),
+            featureVars=data.get("featureVars", {}),
+            metaData=data.get("metaData"),
+        )
+
+
+@dataclass()
+class UserEventsBatchRecord:
+    """
+    A collection of events generated by local bucketing library for a single user
+    """
+
+    user: DevCycleUser
+    events: List[RequestEvent]
+
+    def to_json(self) -> Dict[str, Any]:
+        return {
+            "user": self.user.to_json(),
+            "events": [event.to_json() for event in self.events],
+        }
+
+    @classmethod
+    def from_json(cls, data: dict) -> "UserEventsBatchRecord":
+        return cls(
+            user=DevCycleUser.from_json(data["user"]),
+            events=[RequestEvent.from_json(element) for element in data["events"]],
+        )
+
+
+@dataclass()
+class FlushPayload:
+    """
+    A collection of events exported by the local bucketing library that can be sent to the Events API as a batch
+    """
+
+    payloadId: str
+    records: List[UserEventsBatchRecord]
+    eventCount: int
+
+    @classmethod
+    def from_json(cls, data: dict) -> "FlushPayload":
+        return cls(
+            payloadId=data["payloadId"],
+            eventCount=data["eventCount"],
+            records=[
+                UserEventsBatchRecord.from_json(element) for element in data["records"]
+            ],
+        )

devcycle_python_sdk/models/feature.py

@@ -19,3 +19,15 @@ class Feature:
             for key in self.__dataclass_fields__
             if getattr(self, key) is not None
         }
+
+    @classmethod
+    def from_json(cls, data: dict) -> "Feature":
+        return cls(
+            _id=data["_id"],
+            key=data["key"],
+            type=data["type"],
+            _variation=data["_variation"],
+            variationName=data["variationName"],
+            variationKey=data["variationKey"],
+            evalReason=data.get("evalReason"),
+        )

devcycle_python_sdk/models/platform_data.py

@@ -0,0 +1,33 @@
+# ruff: noqa: N815
+import platform
+import socket
+from dataclasses import dataclass
+from devcycle_python_sdk.util.version import sdk_version
+
+
+@dataclass(order=False)
+class PlatformData:
+    sdkType: str
+    sdkVersion: str
+    platformVersion: str
+    deviceModel: str
+    platform: str
+    hostname: str
+
+    def to_json(self):
+        return {
+            key: getattr(self, key)
+            for key in self.__dataclass_fields__
+            if getattr(self, key) is not None
+        }
+
+
+def default_platform_data() -> PlatformData:
+    return PlatformData(
+        sdkType="server",
+        sdkVersion=sdk_version(),
+        platformVersion=platform.python_version(),
+        deviceModel=platform.platform(),
+        platform="Python",
+        hostname=socket.gethostname(),
+    )

devcycle_python_sdk/models/user.py

@@ -1,11 +1,11 @@
 # ruff: noqa: N815
 from dataclasses import dataclass, field
-from time import time
+from datetime import datetime, timezone
 from typing import Dict, Optional
 
 
 @dataclass(order=False)
-class User:
+class DevCycleUser:
     user_id: str
     email: Optional[str] = None
     name: Optional[str] = None
@@ -13,10 +13,10 @@ class User:
     country: Optional[str] = None
     appVersion: Optional[str] = None
     appBuild: Optional[str] = None
-    customData: Dict[str, str] = field(default_factory=dict)
-    privateCustomData: Dict[str, str] = field(default_factory=dict)
-    createdDate: int = field(default_factory=lambda: int(time()))
-    lastSeenDate: Optional[int] = None  # TODO: accept datetime
+    customData: Optional[Dict[str, str]] = None
+    createdDate: datetime = field(default_factory=lambda: datetime.utcnow())
+    privateCustomData: Optional[Dict[str, str]] = None
+    lastSeenDate: Optional[datetime] = None
     platform: Optional[str] = None
     platformVersion: Optional[str] = None
     deviceModel: Optional[str] = None
@@ -24,8 +24,53 @@ class User:
     sdkVersion: Optional[str] = None
 
     def to_json(self):
-        return {
+        json_dict = {
             key: getattr(self, key)
             for key in self.__dataclass_fields__
             if getattr(self, key) is not None
+            and key not in ["createdDate", "lastSeenDate"]
         }
+
+        if self.createdDate:
+            json_dict["createdDate"] = self.createdDate.astimezone(
+                tz=timezone.utc
+            ).isoformat()
+        if self.lastSeenDate:
+            json_dict["lastSeenDate"] = self.lastSeenDate.astimezone(
+                tz=timezone.utc
+            ).isoformat()
+        return json_dict
+
+    @classmethod
+    def from_json(cls, data: dict) -> "DevCycleUser":
+        if "createdDate" in data:
+            created_date = datetime.fromisoformat(
+                data["createdDate"].replace("Z", "+00:00")
+            )
+        else:
+            created_date = datetime.utcnow()
+
+        last_seen_date = None
+        if "lastSeenDate" in data:
+            last_seen_date = datetime.fromisoformat(
+                data["lastSeenDate"].replace("Z", "+00:00")
+            )
+
+        return cls(
+            user_id=data["user_id"],
+            email=data.get("email"),
+            name=data.get("name"),
+            language=data.get("language"),
+            country=data.get("country"),
+            appVersion=data.get("appVersion"),
+            appBuild=data.get("appBuild"),
+            customData=data.get("customData"),
+            privateCustomData=data.get("privateCustomData"),
+            createdDate=created_date,
+            lastSeenDate=last_seen_date,
+            platform=data.get("platform"),
+            platformVersion=data.get("platformVersion"),
+            deviceModel=data.get("deviceModel"),
+            sdkType=data.get("sdkType"),
+            sdkVersion=data.get("sdkVersion"),
+        )

devcycle_python_sdk/models/variable.py

@@ -26,12 +26,12 @@ def determine_variable_type(value: Any) -> str:
 @dataclass(order=False)
 class Variable:
     _id: Optional[str]
-    key: Optional[str]
-    type: Optional[str]
-    value: Optional[Any] = None
+    key: str
+    type: str
+    value: Any = None
     isDefaulted: Optional[bool] = False
-    defaultValue: Optional[Any] = None
-    # evalReason: Optional[str] = None
+    defaultValue: Any = None
+    evalReason: Optional[str] = None
 
     def to_json(self):
         return {
@@ -40,6 +40,18 @@ class Variable:
             if getattr(self, key) is not None
         }
 
+    @classmethod
+    def from_json(cls, data: dict) -> "Variable":
+        return cls(
+            _id=data["_id"],
+            key=data["key"],
+            type=data["type"],
+            value=data["value"],
+            isDefaulted=data.get("isDefaulted", None),
+            defaultValue=data.get("defaultValue"),
+            evalReason=data.get("evalReason"),
+        )
+
     @staticmethod
     def create_default_variable(key: str, default_value: Any) -> "Variable":
         var_type = determine_variable_type(default_value)

devcycle_python_sdk/options.py

@@ -0,0 +1,106 @@
+import logging
+from typing import Callable, Optional, Dict, Any
+
+logger = logging.getLogger(__name__)
+
+
+class DevCycleCloudOptions:
+    """
+    Options for configuring the DevCycle Cloud SDK.
+    """
+
+    def __init__(
+        self,
+        enable_edge_db: bool = False,
+        bucketing_api_uri: str = "https://bucketing-api.devcycle.com/",
+        request_timeout: int = 5,  # seconds
+        request_retries: int = 5,
+        retry_delay: int = 200,  # milliseconds
+    ):
+        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
+
+
+class DevCycleLocalOptions:
+    """
+    Options for configuring the DevCycle Local Bucketing SDK.
+    """
+
+    def __init__(
+        self,
+        config_cdn_uri: str = "https://config-cdn.devcycle.com/",
+        config_request_timeout_ms: int = 5000,
+        config_polling_interval_ms: int = 1000,
+        config_retry_delay_ms: int = 200,  # milliseconds
+        on_client_initialized: Optional[Callable] = None,
+        events_api_uri: str = "https://events.devcycle.com/",
+        max_event_queue_size: int = 2000,
+        event_flush_interval_ms: int = 10000,
+        flush_event_queue_size: int = 1000,
+        event_request_chunk_size: int = 100,
+        event_request_timeout_ms: int = 10000,
+        event_retry_delay_ms: int = 200,  # milliseconds
+        disable_automatic_event_logging: bool = False,
+        disable_custom_event_logging: bool = False,
+    ):
+        self.events_api_uri = events_api_uri
+        self.config_cdn_uri = config_cdn_uri
+        self.config_request_timeout_ms = config_request_timeout_ms
+        self.config_polling_interval_ms = config_polling_interval_ms
+        self.max_event_queue_size = max_event_queue_size
+        self.event_flush_interval_ms = event_flush_interval_ms
+        self.flush_event_queue_size = flush_event_queue_size
+        self.event_request_chunk_size = event_request_chunk_size
+        self.disable_automatic_event_logging = disable_automatic_event_logging
+        self.disable_custom_event_logging = disable_custom_event_logging
+        self.config_retry_delay_ms = config_retry_delay_ms
+        self.on_client_initialized = on_client_initialized
+        self.event_request_timeout_ms = event_request_timeout_ms
+        self.event_retry_delay_ms = event_retry_delay_ms
+
+        if self.flush_event_queue_size >= self.max_event_queue_size:
+            logger.warning(
+                f"flush_event_queue_size: {self.flush_event_queue_size} must be smaller than max_event_queue_size: {self.max_event_queue_size}"
+            )
+            self.flush_event_queue_size = self.max_event_queue_size - 1
+
+        if self.event_request_chunk_size > self.flush_event_queue_size:
+            logger.warning(
+                f"event_request_chunk_size: {self.event_request_chunk_size} must be smaller than flush_event_queue_size: {self.flush_event_queue_size}"
+            )
+            self.event_request_chunk_size = 100
+
+        if self.event_request_chunk_size > self.max_event_queue_size:
+            logger.warning(
+                f"event_request_chunk_size: {self.event_request_chunk_size} must be smaller than max_event_queue_size: { self.max_event_queue_size}"
+            )
+            self.event_request_chunk_size = 100
+
+        if self.flush_event_queue_size > 20000:
+            logger.warning(
+                f"flush_event_queue_size: {self.flush_event_queue_size} must be smaller than 20,000"
+            )
+            self.flush_event_queue_size = 20000
+
+        if self.max_event_queue_size > 20000:
+            logger.warning(
+                f"max_event_queue_size: {self.max_event_queue_size} must be smaller than 20,000"
+            )
+            self.max_event_queue_size = 20000
+
+    def event_queue_options(self) -> Dict[str, Any]:
+        """
+        Returns a read-only view of the options that are relevant to the event subsystem
+        """
+        return {
+            "flushEventsMS": self.event_flush_interval_ms,
+            "disableAutomaticEventLogging": self.disable_automatic_event_logging,
+            "disableCustomEventLogging": self.disable_custom_event_logging,
+            "maxEventsPerFlush": self.max_event_queue_size,
+            "minEventsPerFlush": self.flush_event_queue_size,
+            "eventRequestChunkSize": self.event_request_chunk_size,
+            "eventsAPIBasePath": self.events_api_uri,
+        }

devcycle_python_sdk/protobuf/utils.py

@@ -0,0 +1,129 @@
+import json
+import logging
+import math
+
+from typing import Any, Optional
+
+from devcycle_python_sdk.models.variable import TypeEnum, Variable
+from devcycle_python_sdk.models.user import DevCycleUser
+
+import devcycle_python_sdk.protobuf.variableForUserParams_pb2 as pb2
+
+logger = logging.getLogger(__name__)
+
+
+def create_nullable_double(val: Optional[float]) -> pb2.NullableDouble:  # type: ignore
+    if val and not math.isnan(val):
+        return pb2.NullableDouble(value=val, isNull=False)  # type: ignore
+    else:
+        return pb2.NullableDouble(isNull=True)  # type: ignore
+
+
+def create_nullable_string(val: Optional[str]) -> pb2.NullableString:  # type: ignore
+    if val is None:
+        return pb2.NullableString(isNull=True)  # type: ignore
+    else:
+        return pb2.NullableString(value=val, isNull=False)  # type: ignore
+
+
+def create_nullable_custom_data(val: Optional[dict]) -> pb2.NullableCustomData:  # type: ignore
+    if val:
+        values = dict()
+        for key, value in val.items():
+            if value is None:
+                values[key] = pb2.CustomDataValue(type=pb2.CustomDataType.Null)  # type: ignore
+            elif isinstance(value, bool):
+                values[key] = pb2.CustomDataValue(type=pb2.CustomDataType.Bool, boolValue=value)  # type: ignore
+            elif isinstance(value, str):
+                values[key] = pb2.CustomDataValue(type=pb2.CustomDataType.Str, stringValue=value)  # type: ignore
+            elif isinstance(value, (int, float)):
+                values[key] = pb2.CustomDataValue(type=pb2.CustomDataType.Num, doubleValue=value)  # type: ignore
+            else:
+                logger.warning(
+                    f"Custom Data contains data type that can't be written, will be ignored. Key: {key}, Type: {str(type(value))}"
+                )
+
+        return pb2.NullableCustomData(value=values, isNull=False)  # type: ignore
+    else:
+        return pb2.NullableCustomData(isNull=True)  # type: ignore
+
+
+def convert_type_enum_to_variable_type(var_type: str) -> pb2.VariableType_PB:
+    if var_type == TypeEnum.BOOLEAN:
+        return pb2.VariableType_PB.Boolean
+    elif var_type == TypeEnum.STRING:
+        return pb2.VariableType_PB.String
+    elif var_type == TypeEnum.NUMBER:
+        return pb2.VariableType_PB.Number
+    elif var_type == TypeEnum.JSON:
+        return pb2.VariableType_PB.JSON
+    else:
+        raise ValueError("Unknown type: " + str(var_type))
+
+
+def create_dvcuser_pb(user: DevCycleUser) -> pb2.DVCUser_PB:  # type: ignore
+    app_build = float("nan")
+    if user.appBuild:
+        try:
+            app_build = float(user.appBuild)
+        except ValueError:
+            pass
+
+    return pb2.DVCUser_PB(  # type: ignore
+        user_id=user.user_id,
+        email=create_nullable_string(user.email),
+        name=create_nullable_string(user.name),
+        language=create_nullable_string(user.language),
+        country=create_nullable_string(user.country),
+        appVersion=create_nullable_string(user.appVersion),
+        appBuild=create_nullable_double(app_build),
+        customData=create_nullable_custom_data(user.customData),
+        privateCustomData=create_nullable_custom_data(user.privateCustomData),
+    )
+
+
+def create_variable(sdk_variable: pb2.SDKVariable_PB, default_value: Any) -> Variable:  # type: ignore
+    if sdk_variable.type == pb2.VariableType_PB.Boolean:  # type: ignore
+        return Variable(
+            _id=None,
+            value=sdk_variable.boolValue,
+            key=sdk_variable.key,
+            type=TypeEnum.BOOLEAN,
+            isDefaulted=False,
+            defaultValue=default_value,
+        )
+
+    elif sdk_variable.type == pb2.VariableType_PB.String:  # type: ignore
+        return Variable(
+            _id=None,
+            value=sdk_variable.stringValue,
+            key=sdk_variable.key,
+            type=TypeEnum.STRING,
+            isDefaulted=False,
+            defaultValue=default_value,
+        )
+
+    elif sdk_variable.type == pb2.VariableType_PB.Number:  # type: ignore
+        return Variable(
+            _id=None,
+            value=sdk_variable.doubleValue,
+            key=sdk_variable.key,
+            type=TypeEnum.NUMBER,
+            isDefaulted=False,
+            defaultValue=default_value,
+        )
+
+    elif sdk_variable.type == pb2.VariableType_PB.JSON:  # type: ignore
+        json_data = json.loads(sdk_variable.stringValue)
+
+        return Variable(
+            _id=None,
+            value=json_data,
+            key=sdk_variable.key,
+            type=TypeEnum.JSON,
+            isDefaulted=False,
+            defaultValue=default_value,
+        )
+
+    else:
+        raise ValueError("Unknown type: " + sdk_variable.type)