devcycle-python-server-sdk 1.2.1__tar.gz → 3.5.0__tar.gz

devcycle-python-server-sdk-3.5.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 1.0
+Name: devcycle-python-server-sdk
+Version: 3.5.0
+Summary: DevCycle Python SDK
+Home-page: https://github.com/devcycleHQ/python-server-sdk
+Author: UNKNOWN
+Author-email: UNKNOWN
+License: UNKNOWN
+Description:     The DevCycle Python SDK used for feature management.
+            
+Keywords: DevCycle
+Platform: UNKNOWN

devcycle-python-server-sdk-3.5.0/README.md

@@ -0,0 +1,119 @@
+# DevCycle Python Server SDK
+
+The DevCycle Python SDK used for feature management.
+
+This SDK allows your application to interface with the [DevCycle Bucketing API](https://docs.devcycle.com/bucketing-api/#tag/devcycle).
+
+## Requirements.
+
+* Python 3.8+
+
+## Installation
+
+```sh
+pip install devcycle-python-server-sdk
+```
+(you may need to run `pip` with root permission: `sudo pip install devcycle-python-server-sdk`)
+
+## Getting Started
+
+The core DevCycle objects are in the `devcycle_python_sdk` package. To get started, import the `DevCycleLocalClient` class and the `DevCycleLocalOptions` class. The `DevCycleLocalClient` class is used to interact with the DevCycle API. The `DevCycleLocalOptions` class is used to configure the client.
+
+```python
+from devcycle_python_sdk import DevCycleLocalClient, DevCycleLocalOptions
+from devcycle_python_sdk.models.user import DevCycleUser
+
+options = DevCycleLocalOptions()
+
+# create an instance of the client class
+client = DevCycleLocalClient('DEVCYCLE_SERVER_SDK_KEY', options)
+
+user = DevCycleUser(
+    user_id='test',
+    email='example@example.ca',
+    country='CA'
+)
+
+value = client.variable_value(user, 'variable-key', 'default-value')
+```
+
+The DevCycle client is designed to work as a singleton in your application. You should create a single instance of the client during application initialization
+
+## OpenFeature Support
+
+This SDK provides an alpha implementation of the [OpenFeature](https://openfeature.dev/) Provider interface. Use the `get_openfeature_provider()` function on the DevCycle SDK client to obtain a provider for OpenFeature.
+
+```python
+from openfeature import api
+
+devcycle_client = DevCycleLocalClient('DEVCYCLE_SERVER_SDK_KEY', options)
+api.set_provider(devcycle_client.get_openfeature_provider())
+```
+
+More details are in the [DevCycle Python SDK OpenFeature Provider](OpenFeature.md) guide.
+
+> :warning: **OpenFeature support is in an early release and may have some rough edges**. Please report any issues to us and we'll be happy to help!
+
+## Usage
+
+To find usage documentation, visit our [docs](https://docs.devcycle.com/docs/sdk/server-side-sdks/python#usage).
+
+## Development
+
+When developing the SDK it is recommended that you have both a 3.8 and 3.12 python interpreter installed in order to verify changes across different versions of python.
+
+### Dependencies
+
+To set up dependencies for local development, run:
+```
+pip install -r requirements.test.txt
+```
+
+To run the example app against the local version of the API for testing and development, run:
+```sh
+pip install --editable .
+```
+from the top level of the repo (same level as setup.py). Then run the example app as normal.
+
+
+### Linting & Formatting
+
+Linting checks on PRs are run using [ruff](https://github.com/charliermarsh/ruff), and are configured using `.ruff.toml`. To run the linter locally, run this command from the top level of the repo:
+```
+ruff check .
+```
+
+Ruff can automatically fix simple linting errors (the ones marked with `[*]`). To do so, run:
+```
+ruff check . --fix
+```
+
+Formatting checks on PRs are done using [black](https://github.com/psf/black). To run the formatter locally, run this command from the top level of the repo:
+
+```
+black .
+```
+
+### Unit Tests
+
+To run the unit tests, run:
+```bash
+pytest
+```
+
+### Benchmarks
+
+To run the benchmarks, run:
+```bash
+pytest --benchmark-only
+```
+
+### Protobuf Code Generation
+
+To generate the protobuf source files run the following from the root of the project. Ensure you have `protoc` installed.
+
+```bash
+protoc --proto_path=./protobuf/ --python_out=devcycle_python_sdk/protobuf --pyi_out=devcycle_python_sdk/protobuf variableForUserParams.proto
+```
+
+This will rebuild the `variableForUserParams_pb2.py` file. DO NOT edit this file directly.

devcycle-python-server-sdk-3.5.0/devcycle_python_sdk/__init__.py

@@ -0,0 +1,6 @@
+# Simplify imports for the SDK entry point objects
+
+from devcycle_python_sdk.options import DevCycleCloudOptions, DevCycleLocalOptions
+from devcycle_python_sdk.devcycle_client import AbstractDevCycleClient
+from devcycle_python_sdk.cloud_client import DevCycleCloudClient
+from devcycle_python_sdk.local_client import DevCycleLocalClient

devcycle-python-server-sdk-3.5.0/devcycle_python_sdk/api/backoff.py

@@ -0,0 +1,11 @@
+import math
+import random
+
+
+def exponential_backoff(attempt: int, base_delay: float) -> float:
+    """
+    Exponential backoff starting with 200ms +- 0...40ms jitter
+    """
+    delay = math.pow(2, attempt) * base_delay / 2.0
+    random_sum = delay * 0.1 * random.random()
+    return delay + random_sum

devcycle-python-server-sdk-3.5.0/devcycle_python_sdk/api/bucketing_client.py

@@ -0,0 +1,145 @@
+import logging
+import time
+from typing import Dict, List, Optional
+
+import requests
+
+from devcycle_python_sdk.api.backoff import exponential_backoff
+from devcycle_python_sdk.options import DevCycleCloudOptions
+from devcycle_python_sdk.exceptions import (
+    CloudClientError,
+    NotFoundError,
+    CloudClientUnauthorizedError,
+)
+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.util.strings import slash_join
+
+logger = logging.getLogger(__name__)
+
+
+class BucketingAPIClient:
+    def __init__(self, sdk_key: str, options: DevCycleCloudOptions):
+        self.sdk_key = sdk_key
+        self.options = options
+        self.session = requests.Session()
+        self.session.headers = {
+            "Authorization": sdk_key,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        self.session.max_redirects = 0
+
+    def _url(self, *path_args: str) -> str:
+        return slash_join(self.options.bucketing_api_uri, "v1", *path_args)
+
+    def request(self, method: str, url: str, **kwargs) -> dict:
+        retries_remaining = self.options.request_retries + 1
+        timeout = self.options.request_timeout
+
+        query_params = {}
+        if self.options.enable_edge_db:
+            query_params["enableEdgeDB"] = "true"
+
+        attempts = 1
+        while retries_remaining > 0:
+            request_error: Optional[Exception] = None
+            try:
+                res: requests.Response = self.session.request(
+                    method, url, params=query_params, timeout=timeout, **kwargs
+                )
+
+                if res.status_code == 401:
+                    # Not a retryable error
+                    raise CloudClientUnauthorizedError("Invalid SDK Key")
+                elif res.status_code == 404:
+                    # Not a retryable error
+                    raise NotFoundError(url)
+                elif 400 <= res.status_code < 500:
+                    # Not a retryable error
+                    raise CloudClientError(f"Bad request: HTTP {res.status_code}")
+                elif res.status_code >= 500:
+                    # Retryable error
+                    request_error = CloudClientError(
+                        f"Server error: HTTP {res.status_code}"
+                    )
+            except requests.exceptions.RequestException as e:
+                request_error = e
+
+            if not request_error:
+                break
+
+            logger.debug(
+                f"DevCycle cloud bucketing request failed (attempt {attempts}): {request_error}"
+            )
+            retries_remaining -= 1
+            if retries_remaining:
+                retry_delay = exponential_backoff(
+                    attempts, self.options.retry_delay / 1000.0
+                )
+                time.sleep(retry_delay)
+                attempts += 1
+                continue
+
+            raise CloudClientError(message="Retries exceeded", cause=request_error)
+
+        data: dict = res.json()
+        return data
+
+    def variable(self, key: str, user: DevCycleUser) -> Variable:
+        data = self.request("POST", self._url("variables", key), json=user.to_json())
+
+        return Variable(
+            _id=data.get("_id"),
+            key=data.get("key", ""),
+            type=data.get("type", ""),
+            value=data.get("value"),
+        )
+
+    def variables(self, user: DevCycleUser) -> Dict[str, Variable]:
+        data = self.request("POST", self._url("variables"), json=user.to_json())
+
+        result: Dict[str, Variable] = {}
+        for key, value in data.items():
+            result[key] = Variable(
+                _id=str(value.get("_id")),
+                key=str(value.get("key")),
+                type=str(value.get("type")),
+                value=value.get("value"),
+                isDefaulted=None,
+            )
+
+        return result
+
+    def features(self, user: DevCycleUser) -> Dict[str, Feature]:
+        data = self.request("POST", self._url("features"), json=user.to_json())
+
+        result: Dict[str, Feature] = {}
+        for key, value in data.items():
+            result[key] = Feature(
+                _id=value.get("_id"),
+                key=value.get("key"),
+                type=value.get("type"),
+                _variation=value.get("_variation"),
+                variationKey=value.get("variationKey"),
+                variationName=value.get("variationName"),
+                evalReason=value.get("evalReason"),
+            )
+
+        return result
+
+    def track(self, user: DevCycleUser, events: List[DevCycleEvent]) -> str:
+        data = self.request(
+            "POST",
+            self._url("track"),
+            json={
+                "user": user.to_json(),
+                "events": [
+                    event.to_json(use_bucketing_api_format=True) for event in events
+                ],
+            },
+        )
+        message = data.get("message", "")
+        return message

devcycle-python-server-sdk-3.5.0/devcycle_python_sdk/api/config_client.py

@@ -0,0 +1,118 @@
+import logging
+import time
+from http import HTTPStatus
+from typing import Optional, Tuple
+
+import requests
+
+from devcycle_python_sdk.api.backoff import exponential_backoff
+from devcycle_python_sdk.options import DevCycleLocalOptions
+from devcycle_python_sdk.exceptions import (
+    APIClientError,
+    NotFoundError,
+    APIClientUnauthorizedError,
+)
+from devcycle_python_sdk.util.strings import slash_join
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigAPIClient:
+    def __init__(self, sdk_key: str, options: DevCycleLocalOptions):
+        self.sdk_key = sdk_key
+        self.options = options
+        self.session = requests.Session()
+        self.session.headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        self.session.max_redirects = 0
+        self.max_config_retries = 2
+        self.config_file_url = (
+            slash_join(
+                self.options.config_cdn_uri, "config", "v1", "server", self.sdk_key
+            )
+            + ".json"
+        )
+
+    def get_config(
+        self, config_etag: Optional[str] = None
+    ) -> Tuple[Optional[dict], Optional[str]]:
+        """
+        Get the config from the server. If the config_etag is provided, the server will only return the config if it
+        has changed since the last request. If the config hasn't changed, the server will return a 304 Not Modified
+        response.
+
+        :param config_etag: The etag of the last config request
+
+        :return: A tuple containing the config and the etag of the config. If the config hasn't changed since the last
+        request, the config will be None and the etag will be the same as the last request.
+        """
+        retries_remaining = self.max_config_retries
+        timeout = self.options.config_request_timeout_ms / 1000.0
+
+        url = self.config_file_url
+
+        headers = {}
+        if config_etag:
+            headers["If-None-Match"] = config_etag
+
+        attempts = 1
+        while retries_remaining > 0:
+            request_error: Optional[Exception] = None
+            try:
+                res: requests.Response = self.session.request(
+                    "GET", url, params={}, timeout=timeout, headers=headers
+                )
+
+                if (
+                    res.status_code == HTTPStatus.UNAUTHORIZED
+                    or res.status_code == HTTPStatus.FORBIDDEN
+                ):
+                    # Not a retryable error
+                    raise APIClientUnauthorizedError("Invalid SDK Key")
+                elif res.status_code == HTTPStatus.NOT_MODIFIED:
+                    # the config hasn't changed since the last request
+                    # don't return anything
+                    return None, config_etag
+                elif res.status_code == HTTPStatus.NOT_FOUND:
+                    # Not a retryable error
+                    raise NotFoundError(url)
+                elif (
+                    HTTPStatus.BAD_REQUEST
+                    <= res.status_code
+                    < HTTPStatus.INTERNAL_SERVER_ERROR
+                ):
+                    # Not a retryable error
+                    raise APIClientError(f"Bad request: HTTP {res.status_code}")
+                elif res.status_code >= HTTPStatus.INTERNAL_SERVER_ERROR:
+                    # Retryable error
+                    request_error = APIClientError(
+                        f"Server error: HTTP {res.status_code}"
+                    )
+                else:
+                    pass
+            except requests.exceptions.RequestException as e:
+                request_error = e
+
+            if not request_error:
+                break
+
+            logger.debug(
+                f"DevCycle config CDN request failed (attempt {attempts}): {request_error}"
+            )
+            retries_remaining -= 1
+            if retries_remaining:
+                retry_delay = exponential_backoff(
+                    attempts, self.options.config_retry_delay_ms / 1000.0
+                )
+                time.sleep(retry_delay)
+                attempts += 1
+                continue
+
+            raise APIClientError(message="Retries exceeded", cause=request_error)
+
+        new_etag = res.headers.get("ETag", None)
+
+        data: dict = res.json()
+        return data, new_etag

devcycle-python-server-sdk-3.5.0/devcycle_python_sdk/api/event_client.py

@@ -0,0 +1,95 @@
+import json
+import logging
+import time
+from typing import Optional, List
+
+import requests
+
+from devcycle_python_sdk.api.backoff import exponential_backoff
+from devcycle_python_sdk.options import DevCycleLocalOptions
+from devcycle_python_sdk.exceptions import (
+    APIClientError,
+    NotFoundError,
+    APIClientUnauthorizedError,
+)
+from devcycle_python_sdk.models.event import UserEventsBatchRecord
+from devcycle_python_sdk.util.strings import slash_join
+
+logger = logging.getLogger(__name__)
+
+
+class EventAPIClient:
+    def __init__(self, sdk_key: str, options: DevCycleLocalOptions):
+        self.options = options
+        self.session = requests.Session()
+        self.session.headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Authorization": sdk_key,
+        }
+        self.session.max_redirects = 0
+        self.max_batch_retries = 0  # we don't retry events batches
+        self.batch_url = slash_join(self.options.events_api_uri, "v1/events/batch")
+
+    def publish_events(self, batch: List[UserEventsBatchRecord]) -> str:
+        """
+        Attempts to send a batch of events to the server
+        """
+        retries_remaining = self.max_batch_retries + 1
+        timeout = self.options.event_request_timeout_ms
+
+        payload_json = json.dumps(
+            {
+                "batch": [record.to_json() for record in batch],
+            }
+        )
+
+        attempts = 1
+        while retries_remaining > 0:
+            request_error: Optional[Exception] = None
+            try:
+                res: requests.Response = self.session.request(
+                    "POST",
+                    self.batch_url,
+                    params={},
+                    timeout=timeout,
+                    data=payload_json,
+                )
+                if res.status_code == 401 or res.status_code == 403:
+                    # Not a retryable error
+                    raise APIClientUnauthorizedError("Invalid SDK Key")
+                elif res.status_code == 404:
+                    # Not a retryable error - bad URL
+                    raise NotFoundError(self.batch_url)
+                elif 400 <= res.status_code < 500:
+                    # Not a retryable error
+                    raise APIClientError(
+                        f"Bad request: HTTP {res.status_code} - {res.text}"
+                    )
+                elif res.status_code >= 500:
+                    # Retryable error
+                    request_error = APIClientError(
+                        f"Server error: HTTP {res.status_code}"
+                    )
+            except requests.exceptions.RequestException as e:
+                request_error = e
+
+            if not request_error:
+                break
+
+            logger.debug(
+                f"DevCycle event batch request failed (attempt {attempts}): {request_error}"
+            )
+            retries_remaining -= 1
+            if retries_remaining:
+                retry_delay = exponential_backoff(
+                    attempts, self.options.event_retry_delay_ms / 1000.0
+                )
+                time.sleep(retry_delay)
+                attempts += 1
+                continue
+
+            raise APIClientError(message="Retries exceeded", cause=request_error)
+
+        data: dict = res.json()
+        return data.get("message", None)