devcycle-python-server-sdk 2.0.1__tar.gz → 3.0.0__tar.gz

{devcycle-python-server-sdk-2.0.1 → devcycle-python-server-sdk-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: devcycle-python-server-sdk
-Version: 2.0.1
+Version: 3.0.0
 Summary: DevCycle Python SDK
 Home-page: https://github.com/devcycleHQ/python-server-sdk
 Author-email: 

{devcycle-python-server-sdk-2.0.1 → devcycle-python-server-sdk-3.0.0}/README.md

@@ -15,31 +15,30 @@ pip install devcycle-python-server-sdk
 ```
 (you may need to run `pip` with root permission: `sudo pip install devcycle-python-server-sdk`)
 
-Then import the package:
-```python
-import devcycle_python_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 DevCycleCloudClient, DevCycleCloudOptions
-from devcycle_python_sdk.models.user import User
+from devcycle_python_sdk import DevCycleLocalClient, DevCycleLocalOptions
+from devcycle_python_sdk.models.user import DevCycleUser
 
-options = DevCycleCloudOptions()
+options = DevCycleLocalOptions()
 
 # create an instance of the client class
-dvc = DevCycleCloudClient('YOUR_DVC_SERVER_SDK_KEY', options)
+client = DevCycleLocalClient('DEVCYCLE_SERVER_SDK_KEY', options)
 
-user = User(
+user = DevCycleUser(
     user_id='test',
     email='example@example.ca',
     country='CA'
 )
 
-value = dvc.variable_value(user, 'feature-key', 'default-value')
+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
+
 ## Usage
 
 To find usage documentation, visit our [docs](https://docs.devcycle.com/docs/sdk/server-side-sdks/python#usage).
@@ -62,7 +61,7 @@ pip install --editable .
 from the top level of the repo (same level as setup.py). Then run the example app as normal.
 
 
-### Linting
+### 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:
 ```
@@ -74,9 +73,32 @@ Ruff can automatically fix simple linting errors (the ones marked with `[*]`). T
 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 --target-version py37 --extend-exclude '_pb2\.pyi?$' .
+```
+
 ### Unit Tests
 
 To run the unit tests, run:
 ```bash
-python -m unittest -v
-```
+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.0.0/devcycle_python_sdk/VERSION.txt

@@ -0,0 +1 @@
+3.0.0

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

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

devcycle-python-server-sdk-3.0.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-2.0.1 → devcycle-python-server-sdk-3.0.0}/devcycle_python_sdk/api/bucketing_client.py

@@ -1,22 +1,21 @@
 import logging
-import math
-from os.path import join
-import random
 import time
+from os.path import join
 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.dvc_options import DevCycleCloudOptions
-from devcycle_python_sdk.models.user import User
-from devcycle_python_sdk.models.event import Event
-from devcycle_python_sdk.models.variable import Variable
+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
 
 logger = logging.getLogger(__name__)
 
@@ -34,7 +33,7 @@ class BucketingAPIClient:
         self.session.max_redirects = 0
 
     def _url(self, *path_args: str) -> str:
-        return join(self.options.bucketing_API_URI, "v1", *path_args)
+        return 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
@@ -72,7 +71,7 @@ class BucketingAPIClient:
             if not request_error:
                 break
 
-            logger.error(
+            logger.debug(
                 f"DevCycle cloud bucketing request failed (attempt {attempts}): {request_error}"
             )
             retries_remaining -= 1
@@ -89,17 +88,17 @@ class BucketingAPIClient:
         data: dict = res.json()
         return data
 
-    def variable(self, key: str, user: User) -> Variable:
+    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"),
+            key=data.get("key", ""),
+            type=data.get("type", ""),
             value=data.get("value"),
         )
 
-    def variables(self, user: User) -> Dict[str, Variable]:
+    def variables(self, user: DevCycleUser) -> Dict[str, Variable]:
         data = self.request("POST", self._url("variables"), json=user.to_json())
 
         result: Dict[str, Variable] = {}
@@ -114,7 +113,7 @@ class BucketingAPIClient:
 
         return result
 
-    def features(self, user: User) -> Dict[str, Feature]:
+    def features(self, user: DevCycleUser) -> Dict[str, Feature]:
         data = self.request("POST", self._url("features"), json=user.to_json())
 
         result: Dict[str, Feature] = {}
@@ -131,23 +130,16 @@ class BucketingAPIClient:
 
         return result
 
-    def track(self, user: User, events: List[Event]) -> str:
+    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() for event in events],
+                "events": [
+                    event.to_json(use_bucketing_api_format=True) for event in events
+                ],
             },
         )
         message = data.get("message", "")
         return message
-
-
-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.0.0/devcycle_python_sdk/api/config_client.py

@@ -0,0 +1,116 @@
+import logging
+import time
+from http import HTTPStatus
+from os.path import join
+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,
+)
+
+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 = (
+            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.0.0/devcycle_python_sdk/api/event_client.py

@@ -0,0 +1,95 @@
+import json
+import logging
+import time
+from os.path import join
+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
+
+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 = 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)