feat: Add asynchronous client

Author: mykola-mokhnach-parloa

.github/workflows/pull_request.yml

@@ -4,6 +4,9 @@ on:
   push:
   pull_request:
 
+concurrency:
+  cancel-in-progress: true
+  group: CI-${{ github.ref }}
 
 jobs:
   main:
@@ -30,6 +33,7 @@ jobs:
           coveralls --service=github
 
   tox:
+    timeout-minutes: 10
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:

README.md

@@ -24,6 +24,8 @@ pip install UnleashClient
 You must initialize the SDK before you use it. Note that until the SDK has synchronized with the API, all features will evaluate to `false` unless
 you have a [bootstrapped configuration](#bootstrap) or you use [fallbacks](#fallback-function).
 
+#### Synchronous Client
+
 ```python
 from UnleashClient import UnleashClient
 
@@ -35,6 +37,27 @@ client = UnleashClient(
 client.initialize_client()
 ```
 
+#### Asynchronous Client
+
+The SDK also supports asynchronous operations using `asyncio`:
+
+```python
+import asyncio
+from UnleashClient.asynchronous import AsyncUnleashClient
+
+async def main():
+    async with AsyncUnleashClient(
+        url="https:<YOUR-API-URL>",
+        app_name="my-python-app",
+        custom_headers={'Authorization': '<API token>'}
+    ) as client:
+        # Client is automatically initialized
+        enabled = client.is_enabled("my_toggle")
+        print(enabled)
+
+asyncio.run(main())
+```
+
 ### Check features
 
 Once the SDK is initialized, you can evaluate toggles using the `is_enabled` or `get_variant` methods.
@@ -61,10 +84,20 @@ print(variant)
 
 If your program no longer needs the SDK, you can call `destroy()`, which shuts down the SDK and flushes any pending metrics to Unleash.
 
+#### Synchronous Client
+
 ```python
 client.destroy()
 ```
 
+#### Asynchronous Client
+
+```python
+await client.destroy()
+```
+
+When using the async client as a context manager (recommended), cleanup is handled automatically.
+
 ## Usage
 
 ### Context

UnleashClient/api/asynchronous/__init__.py

@@ -0,0 +1,6 @@
+# flake8: noqa
+from .features import get_feature_toggles
+from .metrics import send_metrics
+from .register import register_client
+
+__all__ = ["get_feature_toggles", "send_metrics", "register_client"]

UnleashClient/api/asynchronous/features.py

@@ -0,0 +1,88 @@
+from typing import Optional, Tuple
+
+import niquests as requests
+
+from ...constants import FEATURES_URL
+from ...utils import LOGGER, log_resp_info
+
+
+# pylint: disable=broad-except
+async def get_feature_toggles(
+    url: str,
+    app_name: str,
+    instance_id: str,
+    headers: dict,
+    custom_options: dict,
+    request_timeout: int,
+    request_retries: int,
+    project: Optional[str] = None,
+    cached_etag: str = "",
+) -> Tuple[str, str]:
+    """
+    Retrieves feature flags from unleash central server asynchronously.
+
+    Notes:
+    * If unsuccessful (i.e. not HTTP status code 200), exception will be caught and logged.
+      This is to allow "safe" error handling if unleash server goes down.
+
+    :param url:
+    :param app_name:
+    :param instance_id:
+    :param headers:
+    :param custom_options:
+    :param request_timeout:
+    :param request_retries:
+    :param project:
+    :param cached_etag:
+    :return: (Feature flags, etag) if successful, ({},'') if not
+    """
+    try:
+        LOGGER.info("Getting feature flag.")
+
+        request_specific_headers = {
+            "UNLEASH-APPNAME": app_name,
+            "UNLEASH-INSTANCEID": instance_id,
+        }
+
+        if cached_etag:
+            request_specific_headers["If-None-Match"] = cached_etag
+
+        base_url = f"{url}{FEATURES_URL}"
+        base_params = {}
+
+        if project:
+            base_params = {"project": project}
+
+        async with requests.AsyncSession() as session:
+            resp = await session.get(
+                base_url,
+                headers={**headers, **request_specific_headers},
+                params=base_params,
+                timeout=request_timeout,
+                **custom_options,
+            )
+
+        if resp.status_code not in [200, 304]:
+            log_resp_info(resp)
+            LOGGER.warning(
+                "Unleash Client feature fetch failed due to unexpected HTTP status code: %s",
+                resp.status_code,
+            )
+            raise Exception(
+                "Unleash Client feature fetch failed!"
+            )  # pylint: disable=broad-exception-raised
+
+        etag = ""
+        if "etag" in resp.headers.keys():
+            etag = resp.headers["etag"]  # type: ignore[assignment]
+
+        if resp.status_code == 304:
+            return None, etag
+
+        return resp.text, etag
+    except Exception as exc:
+        LOGGER.exception(
+            "Unleash Client feature fetch failed due to exception: %s", exc
+        )
+
+    return None, ""

UnleashClient/api/asynchronous/metrics.py

@@ -0,0 +1,59 @@
+import json
+
+import niquests as requests
+
+from ...constants import APPLICATION_HEADERS, METRICS_URL
+from ...utils import LOGGER, log_resp_info
+
+
+# pylint: disable=broad-except
+async def send_metrics(
+    url: str,
+    request_body: dict,
+    headers: dict,
+    custom_options: dict,
+    request_timeout: int,
+) -> bool:
+    """
+    Attempts to send metrics to Unleash server asynchronously
+
+    Notes:
+    * If unsuccessful (i.e. not HTTP status code 200), message will be logged
+
+    :param url:
+    :param request_body:
+    :param headers:
+    :param custom_options:
+    :param request_timeout:
+    :return: true if registration successful, false if registration unsuccessful or exception.
+    """
+    try:
+        LOGGER.info("Sending messages to with unleash @ %s", url)
+        LOGGER.info("unleash metrics information: %s", request_body)
+
+        async with requests.AsyncSession() as session:
+            resp = await session.post(
+                url + METRICS_URL,
+                data=json.dumps(request_body),
+                headers={**headers, **APPLICATION_HEADERS},
+                timeout=request_timeout,
+                **custom_options,
+            )
+
+        if resp.status_code != 202:
+            log_resp_info(resp)
+            LOGGER.warning(
+                "Unleash Client metrics submission due to unexpected HTTP status code: %s",
+                resp.status_code,
+            )
+            return False
+
+        LOGGER.info("Unleash Client metrics successfully sent!")
+
+        return True
+    except requests.RequestException as exc:
+        LOGGER.warning(
+            "Unleash Client metrics submission failed due to exception: %s", exc
+        )
+
+    return False

UnleashClient/api/asynchronous/register.py

@@ -0,0 +1,94 @@
+import json
+from datetime import datetime, timezone
+from platform import python_implementation, python_version
+
+import niquests as requests
+import yggdrasil_engine
+from niquests.exceptions import InvalidHeader, InvalidSchema, InvalidURL, MissingSchema
+
+from ...constants import (
+    APPLICATION_HEADERS,
+    CLIENT_SPEC_VERSION,
+    REGISTER_URL,
+    SDK_NAME,
+    SDK_VERSION,
+)
+from ...utils import LOGGER, log_resp_info
+
+
+# pylint: disable=broad-except
+async def register_client(
+    url: str,
+    app_name: str,
+    instance_id: str,
+    connection_id: str,
+    metrics_interval: int,
+    headers: dict,
+    custom_options: dict,
+    supported_strategies: dict,
+    request_timeout: int,
+) -> bool:
+    """
+    Attempts to register client with unleash server asynchronously.
+
+    Notes:
+    * If unsuccessful (i.e. not HTTP status code 202), exception will be caught and logged.
+      This is to allow "safe" error handling if unleash server goes down.
+
+    :param url:
+    :param app_name:
+    :param instance_id:
+    :param metrics_interval:
+    :param headers:
+    :param custom_options:
+    :param supported_strategies:
+    :param request_timeout:
+    :return: true if registration successful, false if registration unsuccessful or exception.
+    """
+    registration_request = {
+        "appName": app_name,
+        "instanceId": instance_id,
+        "connectionId": connection_id,
+        "sdkVersion": f"{SDK_NAME}:{SDK_VERSION}",
+        "strategies": [*supported_strategies],
+        "started": datetime.now(timezone.utc).isoformat(),
+        "interval": metrics_interval,
+        "platformName": python_implementation(),
+        "platformVersion": python_version(),
+        "yggdrasilVersion": yggdrasil_engine.__yggdrasil_core_version__,
+        "specVersion": CLIENT_SPEC_VERSION,
+    }
+
+    try:
+        LOGGER.info("Registering unleash client with unleash @ %s", url)
+        LOGGER.info("Registration request information: %s", registration_request)
+
+        async with requests.AsyncSession() as session:
+            resp = await session.post(
+                url + REGISTER_URL,
+                data=json.dumps(registration_request),
+                headers={**headers, **APPLICATION_HEADERS},
+                timeout=request_timeout,
+                **custom_options,
+            )
+
+        if resp.status_code not in {200, 202}:
+            log_resp_info(resp)
+            LOGGER.warning(
+                "Unleash Client registration failed due to unexpected HTTP status code: %s",
+                resp.status_code,
+            )
+            return False
+
+        LOGGER.info("Unleash Client successfully registered!")
+
+        return True
+    except (MissingSchema, InvalidSchema, InvalidHeader, InvalidURL) as exc:
+        LOGGER.exception(
+            "Unleash Client registration failed fatally due to exception: %s", exc
+        )
+        raise exc
+    except requests.RequestException as exc:
+        LOGGER.exception("Unleash Client registration failed due to exception: %s", exc)
+
+    return False

UnleashClient/api/features.py

@@ -81,7 +81,7 @@ def get_feature_toggles(
 
         etag = ""
         if "etag" in resp.headers.keys():
-            etag = resp.headers["etag"]
+            etag = resp.headers["etag"]  # type: ignore[assignment]
 
         if resp.status_code == 304:
             return None, etag