envflags 0.1.0__py3-none-any.whl

envflags/__init__.py

@@ -0,0 +1,12 @@
+from .client import Client, EnvflagsError, create_client
+from .evaluate import Context, Payload, bucket, evaluate
+
+__all__ = [
+    "Client",
+    "Context",
+    "EnvflagsError",
+    "Payload",
+    "bucket",
+    "create_client",
+    "evaluate",
+]

envflags/client.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+import json
+import math
+import threading
+from typing import Any, Callable, Dict, Mapping, Optional, Tuple, TypeVar
+from urllib.error import HTTPError, URLError
+from urllib.parse import urljoin, urlparse
+from urllib.request import Request, urlopen
+
+from .evaluate import Context, Payload, evaluate
+
+DEFAULT_BASE_URL = "https://envflags.com"
+DEFAULT_POLL_INTERVAL = 30.0
+T = TypeVar("T")
+
+
+class EnvflagsError(Exception):
+    pass
+
+
+class Client:
+    def __init__(
+        self,
+        sdk_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        bootstrap: Optional[Payload] = None,
+        opener: Callable[[Request], Any] = urlopen,
+        on_error: Optional[Callable[[Exception], None]] = None,
+        poll_interval: Optional[float] = DEFAULT_POLL_INTERVAL,
+    ) -> None:
+        normalized_key = sdk_key.strip()
+        if not normalized_key:
+            raise ValueError("an envflags SDK key is required")
+        parsed_url = urlparse(base_url)
+        if not parsed_url.scheme or not parsed_url.netloc:
+            raise ValueError("envflags base_url must be an absolute URL")
+        if poll_interval is not None and (
+            isinstance(poll_interval, bool)
+            or not isinstance(poll_interval, (int, float))
+            or not math.isfinite(float(poll_interval))
+            or poll_interval < 0
+        ):
+            raise ValueError("poll_interval must be a non-negative finite number or None")
+        if bootstrap is not None:
+            _validate_payload(bootstrap, "bootstrap payload")
+
+        self._sdk_key = normalized_key
+        self._base_url = base_url
+        self._opener = opener
+        self._on_error = on_error or (lambda error: None)
+        self._poll_interval = (
+            float(poll_interval) if poll_interval is not None else None
+        )
+        self._payload: Optional[Payload] = dict(bootstrap) if bootstrap else None
+        self._etag: Optional[str] = None
+
+        self._condition = threading.Condition(threading.RLock())
+        self._refreshing = False
+        self._refresh_result = False
+        self._refresh_error: Optional[Exception] = None
+        self._stop_event = threading.Event()
+        self._poll_thread: Optional[threading.Thread] = None
+
+    @property
+    def initialized(self) -> bool:
+        with self._condition:
+            return self._payload is not None
+
+    @property
+    def version(self) -> Optional[int]:
+        with self._condition:
+            if self._payload is None:
+                return None
+            value = self._payload.get("version")
+            return value if _is_integer(value) else None
+
+    def initialize(self) -> "Client":
+        try:
+            self.refresh()
+        except Exception as error:
+            self._on_error(error)
+            if not self.initialized:
+                raise
+        self._start_polling()
+        return self
+
+    def refresh(self) -> bool:
+        """Poll and atomically install a new payload when its version changes."""
+        with self._condition:
+            if self._refreshing:
+                while self._refreshing:
+                    self._condition.wait()
+                if self._refresh_error is not None:
+                    raise self._refresh_error
+                return self._refresh_result
+            self._refreshing = True
+
+        changed = False
+        error: Optional[Exception] = None
+        try:
+            changed = self._perform_refresh()
+            return changed
+        except Exception as caught:
+            error = caught
+            raise
+        finally:
+            with self._condition:
+                self._refresh_result = changed
+                self._refresh_error = error
+                self._refreshing = False
+                self._condition.notify_all()
+
+    def close(self) -> None:
+        self._stop_event.set()
+        with self._condition:
+            thread = self._poll_thread
+            self._poll_thread = None
+        if thread is not None and thread is not threading.current_thread():
+            thread.join()
+
+    def variation(
+        self, flag_key: str, context: Context, default_value: T
+    ) -> Any:
+        with self._condition:
+            payload = self._payload
+        if payload is None:
+            return default_value
+        return evaluate(payload, flag_key, context, default_value)
+
+    def bool_variation(
+        self, flag_key: str, context: Context, default_value: bool
+    ) -> bool:
+        value = self.variation(flag_key, context, default_value)
+        return value if isinstance(value, bool) else default_value
+
+    def string_variation(
+        self, flag_key: str, context: Context, default_value: str
+    ) -> str:
+        value = self.variation(flag_key, context, default_value)
+        return value if isinstance(value, str) else default_value
+
+    def number_variation(
+        self, flag_key: str, context: Context, default_value: float
+    ) -> float:
+        value = self.variation(flag_key, context, default_value)
+        if (
+            isinstance(value, bool)
+            or not isinstance(value, (int, float))
+            or not math.isfinite(float(value))
+        ):
+            return default_value
+        return float(value)
+
+    def json_variation(
+        self, flag_key: str, context: Context, default_value: T
+    ) -> Any:
+        return self.variation(flag_key, context, default_value)
+
+    def _perform_refresh(self) -> bool:
+        with self._condition:
+            etag = self._etag
+            current_payload = self._payload
+
+        headers = self._headers()
+        if etag:
+            headers["If-None-Match"] = etag
+        status, pointer = self._request_json(
+            urljoin(self._base_url, "/sdk/poll"),
+            headers,
+            "poll for flag updates",
+            allow_not_modified=True,
+        )
+        if status == 304:
+            return False
+        _validate_pointer(pointer)
+
+        if (
+            current_payload is not None
+            and current_payload.get("envId") == pointer["envId"]
+            and current_payload.get("version") == pointer["version"]
+        ):
+            with self._condition:
+                self._etag = pointer["etag"]
+            return False
+
+        _, payload = self._request_json(
+            urljoin(self._base_url, pointer["payloadUrl"]),
+            self._headers(),
+            "fetch the flag payload",
+        )
+        _validate_payload(payload, "payload")
+        if (
+            payload["envId"] != pointer["envId"]
+            or payload["version"] != pointer["version"]
+        ):
+            raise EnvflagsError(
+                "the envflags payload does not match its version pointer"
+            )
+
+        with self._condition:
+            self._payload = payload
+            self._etag = pointer["etag"]
+        return True
+
+    def _request_json(
+        self,
+        url: str,
+        headers: Dict[str, str],
+        action: str,
+        *,
+        allow_not_modified: bool = False,
+    ) -> Tuple[int, Any]:
+        request = Request(url, headers=headers, method="GET")
+        try:
+            with self._opener(request) as response:
+                status = response.status
+                if allow_not_modified and status == 304:
+                    return status, None
+                if status < 200 or status >= 300:
+                    raise EnvflagsError(
+                        f"unable to {action}: envflags returned {status}"
+                    )
+                try:
+                    return status, json.loads(response.read().decode("utf-8"))
+                except (UnicodeDecodeError, json.JSONDecodeError) as error:
+                    raise EnvflagsError(
+                        f"the envflags response for {action} is invalid JSON"
+                    ) from error
+        except HTTPError as error:
+            if allow_not_modified and error.code == 304:
+                error.close()
+                return 304, None
+            error.close()
+            raise EnvflagsError(
+                f"unable to {action}: envflags returned {error.code} {error.reason}"
+            ) from error
+        except URLError as error:
+            raise EnvflagsError(f"unable to {action}: {error.reason}") from error
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self._sdk_key}",
+        }
+
+    def _start_polling(self) -> None:
+        if self._poll_interval is None or self._poll_interval == 0:
+            return
+        with self._condition:
+            if self._poll_thread is not None:
+                return
+            self._stop_event.clear()
+            thread = threading.Thread(
+                target=self._poll,
+                name="envflags-poll",
+                daemon=True,
+            )
+            self._poll_thread = thread
+            thread.start()
+
+    def _poll(self) -> None:
+        assert self._poll_interval is not None
+        while not self._stop_event.wait(self._poll_interval):
+            try:
+                self.refresh()
+            except Exception as error:
+                self._on_error(error)
+
+
+def create_client(sdk_key: str, **options: Any) -> Client:
+    return Client(sdk_key, **options)
+
+
+def _validate_pointer(value: Any) -> None:
+    if (
+        not isinstance(value, Mapping)
+        or not isinstance(value.get("envId"), str)
+        or not value["envId"]
+        or not _is_integer(value.get("version"))
+        or value["version"] < 0
+        or not isinstance(value.get("etag"), str)
+        or not value["etag"]
+        or not isinstance(value.get("payloadUrl"), str)
+        or not value["payloadUrl"]
+    ):
+        raise EnvflagsError("the envflags poll response is invalid")
+
+
+def _validate_payload(value: Any, label: str) -> None:
+    if (
+        not isinstance(value, Mapping)
+        or not isinstance(value.get("envId"), str)
+        or not value["envId"]
+        or not _is_integer(value.get("version"))
+        or value["version"] < 0
+        or not isinstance(value.get("salt"), str)
+        or not value["salt"]
+        or not isinstance(value.get("flags"), Mapping)
+        or not isinstance(value.get("segments"), Mapping)
+    ):
+        raise EnvflagsError(f"the envflags {label} is invalid")
+
+
+def _is_integer(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)

envflags/evaluate.py

@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+from datetime import datetime
+from typing import Any, Dict, Iterable, Mapping, Optional, Set
+
+BUCKET_DENOMINATOR = 1152921504606846975.0
+RFC3339_PATTERN = re.compile(
+    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$"
+)
+
+Context = Mapping[str, Any]
+Payload = Mapping[str, Any]
+
+
+def bucket(flag_key: str, salt: str, bucket_by: str) -> float:
+    """Return the context's bucket using the frozen v1 algorithm."""
+    value = f"{flag_key}.{salt}.{bucket_by}".encode("utf-8")
+    digest = hashlib.sha1(value).hexdigest()
+    return float(int(digest[:15], 16)) / BUCKET_DENOMINATOR
+
+
+def evaluate(
+    payload: Payload,
+    flag_key: str,
+    context: Context,
+    default_value: Any,
+) -> Any:
+    """Evaluate one flag locally, falling back when no variation is valid."""
+    flags = payload.get("flags")
+    flag = flags.get(flag_key) if isinstance(flags, Mapping) else None
+    key = context.get("key")
+    if not isinstance(flag, Mapping) or not isinstance(key, str) or not key:
+        return default_value
+
+    variation: Optional[int] = None
+    if flag.get("on") is not True:
+        variation = _index(flag.get("offVariation"))
+    else:
+        targets = flag.get("targets")
+        if isinstance(targets, list):
+            for target in targets:
+                if not isinstance(target, Mapping):
+                    continue
+                values = target.get("values")
+                if isinstance(values, list) and key in values:
+                    variation = _index(target.get("variation"))
+                    break
+
+        if variation is None:
+            rules = flag.get("rules")
+            if isinstance(rules, list):
+                for rule in rules:
+                    if not isinstance(rule, Mapping):
+                        continue
+                    clauses = rule.get("clauses")
+                    if isinstance(clauses, list) and _clauses_match(
+                        clauses, context, payload, set()
+                    ):
+                        variation = _select_variation(
+                            rule, flag_key, context, payload
+                        )
+                        break
+
+        if variation is None:
+            fallthrough = flag.get("fallthrough")
+            if isinstance(fallthrough, Mapping):
+                variation = _select_variation(
+                    fallthrough, flag_key, context, payload
+                )
+
+    variations = flag.get("variations")
+    if (
+        variation is None
+        or not isinstance(variations, list)
+        or variation < 0
+        or variation >= len(variations)
+    ):
+        return default_value
+    return variations[variation]
+
+
+def _select_variation(
+    selector: Mapping[str, Any],
+    flag_key: str,
+    context: Context,
+    payload: Payload,
+) -> Optional[int]:
+    if "variation" in selector:
+        return _index(selector.get("variation"))
+
+    rollout = selector.get("rollout")
+    if not isinstance(rollout, list) or not rollout:
+        return None
+    last = rollout[-1]
+    if not isinstance(last, Mapping):
+        return None
+
+    bucket_by = selector.get("bucketBy", "key")
+    if not isinstance(bucket_by, str):
+        return None
+    if bucket_by not in context:
+        return _index(last.get("variation"))
+
+    context_bucket = bucket(
+        flag_key,
+        str(payload.get("salt", "")),
+        _stringify(context[bucket_by]),
+    )
+    accumulated_weight = 0.0
+    for entry in rollout:
+        if not isinstance(entry, Mapping):
+            continue
+        weight = entry.get("weight")
+        if not _is_number(weight) or not math.isfinite(float(weight)):
+            continue
+        accumulated_weight += float(weight) / 100_000.0
+        if context_bucket < accumulated_weight:
+            return _index(entry.get("variation"))
+    return _index(last.get("variation"))
+
+
+def _clauses_match(
+    clauses: Iterable[Any],
+    context: Context,
+    payload: Payload,
+    visiting: Set[str],
+) -> bool:
+    return all(
+        isinstance(clause, Mapping)
+        and _clause_matches(clause, context, payload, visiting)
+        for clause in clauses
+    )
+
+
+def _clause_matches(
+    clause: Mapping[str, Any],
+    context: Context,
+    payload: Payload,
+    visiting: Set[str],
+) -> bool:
+    attribute_name = clause.get("attribute")
+    if not isinstance(attribute_name, str) or attribute_name not in context:
+        return False
+    attribute = context[attribute_name]
+    values = clause.get("values")
+    if not isinstance(values, list):
+        return False
+
+    operation = clause.get("op")
+    if operation == "in":
+        return _matches_in(attribute, values)
+    if operation == "notIn":
+        return not _matches_in(attribute, values)
+    if operation == "startsWith":
+        return _matches_strings(attribute, values, str.startswith)
+    if operation == "endsWith":
+        return _matches_strings(attribute, values, str.endswith)
+    if operation == "contains":
+        return _matches_strings(attribute, values, lambda left, right: right in left)
+    if operation == "matches":
+        return _matches_strings(attribute, values, _regex_search)
+    if operation == "lessThan":
+        return _matches_numbers(attribute, values, lambda left, right: left < right)
+    if operation == "greaterThan":
+        return _matches_numbers(attribute, values, lambda left, right: left > right)
+    if operation == "before":
+        return _matches_dates(attribute, values, lambda left, right: left < right)
+    if operation == "after":
+        return _matches_dates(attribute, values, lambda left, right: left > right)
+    if operation == "segmentMatch":
+        return _matches_segments(values, context, payload, visiting)
+    return False
+
+
+def _matches_in(attribute: Any, values: Iterable[Any]) -> bool:
+    attributes = attribute if isinstance(attribute, list) else [attribute]
+    return any(_scalar_equal(item, value) for item in attributes for value in values)
+
+
+def _scalar_equal(left: Any, right: Any) -> bool:
+    if left is None or right is None:
+        return left is None and right is None
+    if isinstance(left, bool) or isinstance(right, bool):
+        return isinstance(left, bool) and isinstance(right, bool) and left == right
+    if _is_number(left) or _is_number(right):
+        return _is_number(left) and _is_number(right) and float(left) == float(right)
+    if isinstance(left, str) or isinstance(right, str):
+        return isinstance(left, str) and isinstance(right, str) and left == right
+    return False
+
+
+def _matches_strings(attribute: Any, values: Iterable[Any], predicate: Any) -> bool:
+    if not isinstance(attribute, str):
+        return False
+    return any(isinstance(value, str) and predicate(attribute, value) for value in values)
+
+
+def _matches_numbers(attribute: Any, values: Iterable[Any], predicate: Any) -> bool:
+    if not _is_finite_number(attribute):
+        return False
+    return any(
+        _is_finite_number(value) and predicate(float(attribute), float(value))
+        for value in values
+    )
+
+
+def _matches_dates(attribute: Any, values: Iterable[Any], predicate: Any) -> bool:
+    left = _instant(attribute)
+    if left is None:
+        return False
+    return any(
+        right is not None and predicate(left, right)
+        for right in (_instant(value) for value in values)
+    )
+
+
+def _matches_segments(
+    values: Iterable[Any],
+    context: Context,
+    payload: Payload,
+    visiting: Set[str],
+) -> bool:
+    segments = payload.get("segments")
+    if not isinstance(segments, Mapping):
+        return False
+    for value in values:
+        if not isinstance(value, str) or value in visiting:
+            continue
+        segment = segments.get(value)
+        if not isinstance(segment, Mapping):
+            continue
+        if _segment_matches(segment, context, payload, visiting | {value}):
+            return True
+    return False
+
+
+def _segment_matches(
+    segment: Mapping[str, Any],
+    context: Context,
+    payload: Payload,
+    visiting: Set[str],
+) -> bool:
+    key = context.get("key")
+    excluded = segment.get("excluded")
+    if isinstance(excluded, list) and key in excluded:
+        return False
+    included = segment.get("included")
+    if isinstance(included, list) and key in included:
+        return True
+    rules = segment.get("rules")
+    if not isinstance(rules, list):
+        return False
+    return any(
+        isinstance(rule, Mapping)
+        and isinstance(rule.get("clauses"), list)
+        and _clauses_match(rule["clauses"], context, payload, visiting)
+        for rule in rules
+    )
+
+
+def _regex_search(left: str, pattern: str) -> bool:
+    try:
+        return re.search(pattern, left) is not None
+    except re.error:
+        return False
+
+
+def _instant(value: Any) -> Optional[float]:
+    if _is_finite_number(value):
+        return float(value)
+    if not isinstance(value, str) or not RFC3339_PATTERN.fullmatch(value):
+        return None
+    try:
+        normalized = value[:-1] + "+00:00" if value.endswith("Z") else value
+        parsed = datetime.fromisoformat(normalized)
+        return parsed.timestamp() * 1000.0
+    except ValueError:
+        return None
+
+
+def _index(value: Any) -> Optional[int]:
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _is_finite_number(value: Any) -> bool:
+    return _is_number(value) and math.isfinite(float(value))
+
+
+def _stringify(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return value
+    if _is_number(value):
+        numeric = float(value)
+        if numeric == 0:
+            return "0"
+        if numeric.is_integer():
+            return str(int(numeric))
+        return repr(numeric)
+    if isinstance(value, list):
+        return ",".join(_stringify(item) for item in value)
+    return "[object Object]"

envflags-0.1.0.dist-info/METADATA

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: envflags
+Version: 0.1.0
+Summary: Python SDK for envflags
+Author: envflags
+License: MIT
+Project-URL: Homepage, https://envflags.com
+Project-URL: Repository, https://github.com/envflags/envflags
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# envflags Python SDK
+
+The Python SDK downloads an immutable delivery payload, keeps the last known
+good copy in memory, and evaluates flags locally using the shared v1 spec.
+
+```python
+from envflags import create_client
+
+flags = create_client("envflags_server_...").initialize()
+try:
+    enabled = flags.bool_variation(
+        "new-checkout",
+        {"key": "user-123", "country": "BE"},
+        False,
+    )
+finally:
+    flags.close()
+```
+
+The client polls every 30 seconds and fetches a payload only when its version
+changes. Set `poll_interval=None` to refresh manually. Supply a previously
+persisted payload through `bootstrap` to remain available when initialization
+is offline. Refresh failures never replace the last known good payload.
+
+The package supports Python 3.9+ and has no third-party dependencies. `evaluate`
+and `bucket` are exported for applications that manage payload delivery
+themselves.

envflags-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+envflags/__init__.py,sha256=jS6u_cnaq9YN9xACCqEF-TGUkwG6dp_TiCtlozKH8UU,245
+envflags/client.py,sha256=hK05lQDuUL8Xrmev8cM_7ZHAn04ZFQcf9VjTiU6poYM,10398
+envflags/evaluate.py,sha256=n-rG7PeHCzu26x6TEaKbUoAU9s1g2INDQXpXNNahhf0,10101
+envflags-0.1.0.dist-info/METADATA,sha256=04_fkp4QqfE5pzG9SQ54RFfsOH_fOxYi9hBBCmR83P8,1198
+envflags-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+envflags-0.1.0.dist-info/top_level.txt,sha256=KYHnMbp984CUTngOIZ85jBqK4pCuBHQcJ_txZuQA1Gs,9
+envflags-0.1.0.dist-info/RECORD,,

envflags-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

envflags-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+envflags