spotify-confidence-sdk 0.2.1__py3-none-any.whl

confidence/__init__.py

@@ -0,0 +1,6 @@
+try:
+    from ._version import version as __version__
+    from ._version import version_tuple
+except ImportError:
+    __version__ = "unknown version"
+    version_tuple = (0, 0, 0, "unknown version")

confidence/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.2.1'
+__version_tuple__ = version_tuple = (0, 2, 1)

confidence/confidence.py

@@ -0,0 +1,286 @@
+import asyncio
+import dataclasses
+from datetime import datetime
+from enum import Enum
+import logging
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+    Type,
+    Union,
+    get_args,
+    get_origin,
+)
+
+import requests
+from typing_extensions import TypeGuard
+
+from confidence import __version__
+from confidence.errors import (
+    FlagNotFoundError,
+    ParseError,
+    TypeMismatchError,
+)
+from .flag_types import FlagResolutionDetails, Reason
+from .names import FlagName, VariantName
+
+EU_RESOLVE_API_ENDPOINT = "https://resolver.eu.confidence.dev/v1"
+US_RESOLVE_API_ENDPOINT = "https://resolver.us.confidence.dev/v1"
+GLOBAL_RESOLVE_API_ENDPOINT = "https://resolver.confidence.dev/v1"
+
+Primitive = Union[str, int, float, bool, None]
+FieldType = Union[Primitive, List[Primitive], List["Object"], "Object"]
+Object = Dict[str, FieldType]
+
+
+def is_primitive(field_type: Type[Any]) -> TypeGuard[Type[Primitive]]:
+    return field_type in get_args(Primitive)
+
+
+def primitive_matches(value: FieldType, value_type: Type[Primitive]) -> bool:
+    return (
+        value_type is None
+        or (value_type is int and isinstance(value, int))
+        or (value_type is float and isinstance(value, float))
+        or (value_type is str and isinstance(value, str))
+        or (value_type is bool and isinstance(value, bool))
+    )
+
+
+class Region(Enum):
+    def endpoint(self) -> str:
+        return self.value
+
+    EU = EU_RESOLVE_API_ENDPOINT
+    US = US_RESOLVE_API_ENDPOINT
+    GLOBAL = GLOBAL_RESOLVE_API_ENDPOINT
+
+
+@dataclasses.dataclass
+class ResolveResult(object):
+    value: Optional[Object]
+    variant: Optional[str]
+    token: str
+
+
+class Confidence:
+    context: Dict[str, FieldType] = {}
+
+    def put_context(self, key: str, value: FieldType) -> None:
+        self.context[key] = value
+
+    def with_context(self, context: Dict[str, FieldType]) -> "Confidence":
+        new_confidence = Confidence(
+            self._client_secret, self._region, self._apply_on_resolve
+        )
+        new_confidence.context = {**self.context, **context}
+        return new_confidence
+
+    def __init__(
+        self,
+        client_secret: str,
+        region: Region = Region.GLOBAL,
+        apply_on_resolve: bool = True,
+        logger: logging.Logger = logging.getLogger("confidence_logger"),
+    ):
+        self._client_secret = client_secret
+        self._region = region
+        self._api_endpoint = region.endpoint()
+        self._apply_on_resolve = apply_on_resolve
+        self.logger = logger
+        self._setup_logger(logger)
+
+    def resolve_boolean_details(
+        self, flag_key: str, default_value: bool
+    ) -> FlagResolutionDetails[bool]:
+        return self._evaluate(flag_key, bool, default_value, self.context)
+
+    def resolve_float_details(
+        self, flag_key: str, default_value: float
+    ) -> FlagResolutionDetails[float]:
+        return self._evaluate(flag_key, float, default_value, self.context)
+
+    def resolve_integer_details(
+        self, flag_key: str, default_value: int
+    ) -> FlagResolutionDetails[int]:
+        return self._evaluate(flag_key, int, default_value, self.context)
+
+    def resolve_string_details(
+        self, flag_key: str, default_value: str
+    ) -> FlagResolutionDetails[str]:
+        return self._evaluate(flag_key, str, default_value, self.context)
+
+    def resolve_object_details(
+        self, flag_key: str, default_value: Union[Object, List[Primitive]]
+    ) -> FlagResolutionDetails[Union[Object, List[Primitive]]]:
+        return self._evaluate(flag_key, Object, default_value, self.context)
+
+    def _setup_logger(self, logger: logging.Logger) -> None:
+        if logger is not None:
+            logger.setLevel(logging.DEBUG)
+            formatter = logging.Formatter(
+                "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+            )
+            if not logger.hasHandlers():
+                ch = logging.StreamHandler()
+                ch.setFormatter(formatter)
+                logger.addHandler(ch)
+
+    #
+    # --- internals
+    #
+
+    def _evaluate(
+        self,
+        flag_key: str,
+        value_type: Type[FieldType],
+        default_value: FieldType,
+        context: Dict[str, FieldType],
+    ) -> FlagResolutionDetails[Any]:
+        if "." in flag_key:
+            flag_id, value_path = flag_key.split(".", 1)
+        else:
+            flag_id = flag_key
+            value_path = None
+        result = self._resolve(FlagName(flag_id), context)
+        if result.variant is None or len(str(result.value)) == 0:
+            return FlagResolutionDetails(
+                value=default_value,
+                reason=Reason.DEFAULT,
+                flag_metadata={"flag_key": flag_key},
+            )
+
+        variant_name = VariantName.parse(result.variant)
+
+        value = self._select(result, value_path, value_type, self.logger)
+        if value is None:
+            self.logger.debug(
+                f"Flag {flag_key} resolved to None. Returning default value."
+            )
+            value = default_value
+
+        return FlagResolutionDetails(
+            value=value,
+            variant=variant_name.variant,
+            reason=Reason.TARGETING_MATCH,
+            flag_metadata={"flag_key": flag_key},
+        )
+
+    # type-arg: ignore
+    def track(self, event_name: str, data: Dict[str, FieldType]) -> None:
+        asyncio.create_task(self._send_event(event_name, data))
+
+    async def track_async(self, event_name: str, data: Dict[str, FieldType]) -> None:
+        await self._send_event(event_name, data)
+
+    async def _send_event(self, event_name: str, data: Dict[str, FieldType]) -> None:
+        current_time = datetime.utcnow().isoformat() + "Z"
+        request_body = {
+            "clientSecret": self._client_secret,
+            "sendTime": current_time,
+            "events": [
+                {
+                    "eventDefinition": f"eventDefinitions/{event_name}",
+                    "payload": {"context": {**self.context}, **data},
+                    "eventTime": current_time,
+                }
+            ],
+            "sdk": {"id": "SDK_ID_PYTHON_CONFIDENCE", "version": __version__},
+        }
+
+        event_url = "https://events.confidence.dev/v1/events:publish"
+        headers = {"Content-Type": "application/json", "Accept": "application/json"}
+        response = requests.post(event_url, json=request_body, headers=headers)
+        response.raise_for_status()
+        json = response.json()
+
+        json_errors = json.get("errors")
+        if json_errors:
+            self.logger.warn("events emitted with errors:")
+            for error in json_errors:
+                self.logger.warn(error)
+
+    def _resolve(
+        self, flag_name: FlagName, context: Dict[str, FieldType]
+    ) -> ResolveResult:
+        request_body = {
+            "clientSecret": self._client_secret,
+            "evaluationContext": context,
+            "apply": self._apply_on_resolve,
+            "flags": [str(flag_name)],
+            "sdk": {"id": "SDK_ID_PYTHON_CONFIDENCE", "version": __version__},
+        }
+
+        resolve_url = f"{self._api_endpoint}/flags:resolve"
+        response = requests.post(resolve_url, json=request_body)
+        if response.status_code == 404:
+            self.logger.error(f"Flag {flag_name} not found")
+            raise FlagNotFoundError()
+
+        response.raise_for_status()
+
+        response_body = response.json()
+
+        resolved_flags = response_body["resolvedFlags"]
+        token = response_body["resolveToken"]
+
+        if len(resolved_flags) == 0:
+            self.logger.info(f"Flag {flag_name} not found")
+            return ResolveResult(None, None, token)
+
+        resolved_flag = resolved_flags[0]
+        variant = resolved_flag.get("variant")
+        return ResolveResult(
+            resolved_flag.get("value"), None if variant == "" else variant, token
+        )
+
+    @staticmethod
+    def _select(
+        result: ResolveResult,
+        value_path: Optional[str],
+        value_type: Type[FieldType],
+        logger: logging.Logger,
+    ) -> FieldType:
+        value: FieldType = result.value
+
+        if value_path is not None:
+            keys = value_path.split(".")
+            for key in keys:
+                if not isinstance(value, dict):
+                    logger.debug(f"Value {value} is not a dict. Returning None.")
+                    raise ParseError()
+
+                if key not in value:
+                    logger.debug(
+                        f"Key {key} not found in value {value}. Returning None."
+                    )
+                    raise ParseError()
+
+                value = value.get(key)
+
+        # skip type checking if the value was not specified
+        if value is None:
+            return None
+
+        if not Confidence.type_matches(value, value_type):
+            logger.debug(
+                f"Type of value {value} did not match expected type {value_type}."
+            )
+            raise TypeMismatchError("type of value did not match excepted type")
+
+        return value
+
+    @staticmethod
+    def type_matches(value: FieldType, value_type: Type[FieldType]) -> bool:
+        origin = get_origin(value_type)
+
+        if is_primitive(value_type):
+            return primitive_matches(value, value_type)
+        elif origin is list:
+            return isinstance(value, list)
+        elif origin is dict:
+            return isinstance(value, dict)
+
+        return False

confidence/errors.py

@@ -0,0 +1,127 @@
+import typing
+from enum import Enum
+
+
+class ErrorCode(Enum):
+    NOT_READY = "NOT_READY"
+    FLAG_NOT_FOUND = "FLAG_NOT_FOUND"
+    PARSE_ERROR = "PARSE_ERROR"
+    TYPE_MISMATCH = "TYPE_MISMATCH"
+    TARGETING_KEY_MISSING = "TARGETING_KEY_MISSING"
+    INVALID_CONTEXT = "INVALID_CONTEXT"
+    GENERAL = "GENERAL"
+
+
+class ConfidenceError(Exception):
+    """
+    A generic confidence exception, this exception should not be raised. Instead
+    the more specific exceptions extending this one should be used.
+    """
+
+    def __init__(
+        self, error_code: ErrorCode, error_message: typing.Optional[str] = None
+    ):
+        """
+        Constructor for the generic ConfidenceError.
+        @param error_message: an optional string message representing why the
+        error has been raised
+        @param error_code: the ErrorCode string enum value for the type of error
+        """
+        self.error_message = error_message
+        self.error_code = error_code
+
+
+class FlagNotFoundError(ConfidenceError):
+    """
+    This exception should be raised when the provider cannot find a flag with the
+    key provided by the user.
+    """
+
+    def __init__(self, error_message: typing.Optional[str] = None):
+        """
+        Constructor for the FlagNotFoundError.  The error code for
+        this type of exception is ErrorCode.FLAG_NOT_FOUND.
+        @param error_message: an optional string message representing
+        why the error has been raised
+        """
+        super().__init__(ErrorCode.FLAG_NOT_FOUND, error_message)
+
+
+class GeneralError(ConfidenceError):
+    """
+    This exception should be raised when the for an exception within the open
+    feature python sdk.
+    """
+
+    def __init__(self, error_message: typing.Optional[str] = None):
+        """
+        Constructor for the GeneralError.  The error code for this type of exception
+        is ErrorCode.GENERAL.
+        @param error_message: an optional string message representing why the error
+        has been raised
+        """
+        super().__init__(ErrorCode.GENERAL, error_message)
+
+
+class ParseError(ConfidenceError):
+    """
+    This exception should be raised when the flag returned by the provider cannot
+    be parsed into a FlagEvaluationDetails object.
+    """
+
+    def __init__(self, error_message: typing.Optional[str] = None):
+        """
+        Constructor for the ParseError. The error code for this type of exception
+        is ErrorCode.PARSE_ERROR.
+        @param error_message: an optional string message representing why the
+        error has been raised
+        """
+        super().__init__(ErrorCode.PARSE_ERROR, error_message)
+
+
+class TypeMismatchError(ConfidenceError):
+    """
+    This exception should be raised when the flag returned by the provider does
+    not match the type requested by the user.
+    """
+
+    def __init__(self, error_message: typing.Optional[str] = None):
+        """
+        Constructor for the TypeMismatchError. The error code for this type of
+        exception is ErrorCode.TYPE_MISMATCH.
+        @param error_message: an optional string message representing why the
+        error has been raised
+        """
+        super().__init__(ErrorCode.TYPE_MISMATCH, error_message)
+
+
+class TargetingKeyMissingError(ConfidenceError):
+    """
+    This exception should be raised when the provider requires a targeting key
+    but one was not provided in the evaluation context.
+    """
+
+    def __init__(self, error_message: typing.Optional[str] = None):
+        """
+        Constructor for the TargetingKeyMissingError. The error code for this type of
+        exception is ErrorCode.TARGETING_KEY_MISSING.
+        @param error_message: a string message representing why the error has been
+        raised
+        """
+        super().__init__(ErrorCode.TARGETING_KEY_MISSING, error_message)
+
+
+class InvalidContextError(ConfidenceError):
+    """
+    This exception should be raised when the evaluation context does not meet provider
+    requirements.
+    """
+
+    def __init__(self, error_message: typing.Optional[str]):
+        """
+        Constructor for the InvalidContextError. The error code for this type of
+        exception is ErrorCode.INVALID_CONTEXT.
+        @param error_message: a string message representing why the error has been
+        raised
+        """
+        super().__init__(ErrorCode.INVALID_CONTEXT, error_message)

confidence/flag_types.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import sys
+import typing
+from dataclasses import dataclass, field
+
+from confidence.errors import ErrorCode
+
+if sys.version_info >= (3, 11):
+    # re-export needed for type checking
+    from enum import StrEnum as StrEnum  # noqa: PLC0414
+else:
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        """
+        Backport StrEnum for Python <3.11
+        """
+
+        pass
+
+
+class FlagType(StrEnum):
+    BOOLEAN = "BOOLEAN"
+    STRING = "STRING"
+    OBJECT = "OBJECT"
+    FLOAT = "FLOAT"
+    INTEGER = "INTEGER"
+
+
+class Reason(StrEnum):
+    CACHED = "CACHED"
+    DEFAULT = "DEFAULT"
+    DISABLED = "DISABLED"
+    ERROR = "ERROR"
+    STATIC = "STATIC"
+    SPLIT = "SPLIT"
+    TARGETING_MATCH = "TARGETING_MATCH"
+    UNKNOWN = "UNKNOWN"
+
+
+FlagMetadata = typing.Mapping[str, typing.Any]
+
+T_co = typing.TypeVar("T_co", covariant=True)
+
+
+@dataclass
+class FlagEvaluationDetails(typing.Generic[T_co]):
+    flag_key: str
+    value: T_co
+    variant: typing.Optional[str] = None
+    flag_metadata: FlagMetadata = field(default_factory=dict)
+    reason: typing.Optional[typing.Union[str, Reason]] = None
+    error_code: typing.Optional[ErrorCode] = None
+    error_message: typing.Optional[str] = None
+
+
+U_co = typing.TypeVar("U_co", covariant=True)
+
+
+@dataclass
+class FlagResolutionDetails(typing.Generic[U_co]):
+    value: U_co
+    error_code: typing.Optional[ErrorCode] = None
+    error_message: typing.Optional[str] = None
+    reason: typing.Optional[typing.Union[str, Reason]] = None
+    variant: typing.Optional[str] = None
+    flag_metadata: FlagMetadata = field(default_factory=dict)

confidence/names.py

@@ -0,0 +1,29 @@
+import dataclasses
+
+
+@dataclasses.dataclass
+class FlagName(object):
+    flag: str
+
+    @classmethod
+    def parse(cls, resource_name: str) -> "FlagName":
+        components = resource_name.split("/", 2)
+        if components[0] != "flags":
+            raise ValueError("name error")
+        return cls(components[1])
+
+    def __str__(self) -> str:
+        return f"flags/{self.flag}"
+
+
+@dataclasses.dataclass
+class VariantName(object):
+    flag: str
+    variant: str
+
+    @classmethod
+    def parse(cls, resource_name: str) -> "VariantName":
+        components = resource_name.split("/")
+        if components[0] != "flags" or components[2] != "variants":
+            raise ValueError("name error")
+        return cls(components[1], components[3])