flagdrop-sdk 0.1.0__tar.gz

flagdrop_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: flagdrop-sdk
+Version: 0.1.0
+Summary: FlagDrop Python SDK — evaluate feature flags from your cloud bucket
+Author-email: FlagDrop <support@flagdrop.io>
+License: MIT
+Project-URL: Homepage, https://flagdrop.io
+Project-URL: Documentation, https://flagdrop.io/docs
+Keywords: feature-flags,flagdrop,sdk,s3,feature-toggles
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: boto3>=1.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: moto[s3]>=5.0; extra == "dev"
+
+# FlagDrop Python SDK
+
+Feature flag evaluation that runs entirely in your cloud. No vendor servers, no data leaving your infrastructure.
+
+## Installation
+
+```bash
+pip install flagdrop-sdk
+```
+
+## Quick Start
+
+```python
+from flagdrop import FlagClient
+
+client = FlagClient(
+    bucket="my-app-flags",
+    environment="production",
+    provider="aws",
+    region="us-east-1",
+)
+client.initialize()
+
+# Boolean flag
+enabled = client.get_bool("new-checkout", False)
+
+# String flag with targeting context
+theme = client.get_string("app-theme", "light", {"plan": "enterprise"})
+
+# Number flag
+max_items = client.get_number("max-items", 10)
+
+# JSON flag
+config = client.get_json("feature-config", {"limit": 5})
+```
+
+## How It Works
+
+1. You define flags in the [FlagDrop dashboard](https://flagdrop.io)
+2. FlagDrop pushes a JSON config file to an S3 bucket in **your** AWS account
+3. The SDK reads that file and evaluates flags locally at runtime
+
+No network calls to FlagDrop servers during evaluation. No latency. No single point of failure.
+
+## Configuration
+
+| Parameter | Description |
+|-----------|-------------|
+| `bucket` | S3 bucket name where flag configs are stored |
+| `environment` | Environment name (e.g., `production`, `staging`) |
+| `provider` | Cloud provider (`aws`) |
+| `region` | AWS region (e.g., `us-east-1`) |
+| `scope` | Config scope: `backend` (default) or `frontend` |
+| `refresh_interval_seconds` | How often to re-fetch config (default: 30s, 0 to disable) |
+
+## Targeting Rules
+
+The SDK evaluates targeting rules locally. Supported operators:
+
+- `eq`, `neq` — exact match / not equal
+- `in`, `notIn` — value in list / not in list
+- `lt`, `gt` — less than / greater than (numeric)
+- `startsWith`, `endsWith`, `contains` — string matching
+- `segment` — segment membership
+
+## Rollouts
+
+Percentage-based rollouts use deterministic hashing, so the same user always gets the same result.
+
+## Requirements
+
+- Python 3.9+
+- `boto3` (AWS SDK)
+- AWS credentials with read access to your flag config bucket
+
+## Links
+
+- [FlagDrop](https://flagdrop.io) — Feature flags in your cloud
+- [Documentation](https://flagdrop.io/docs)

flagdrop_sdk-0.1.0/README.md

@@ -0,0 +1,79 @@
+# FlagDrop Python SDK
+
+Feature flag evaluation that runs entirely in your cloud. No vendor servers, no data leaving your infrastructure.
+
+## Installation
+
+```bash
+pip install flagdrop-sdk
+```
+
+## Quick Start
+
+```python
+from flagdrop import FlagClient
+
+client = FlagClient(
+    bucket="my-app-flags",
+    environment="production",
+    provider="aws",
+    region="us-east-1",
+)
+client.initialize()
+
+# Boolean flag
+enabled = client.get_bool("new-checkout", False)
+
+# String flag with targeting context
+theme = client.get_string("app-theme", "light", {"plan": "enterprise"})
+
+# Number flag
+max_items = client.get_number("max-items", 10)
+
+# JSON flag
+config = client.get_json("feature-config", {"limit": 5})
+```
+
+## How It Works
+
+1. You define flags in the [FlagDrop dashboard](https://flagdrop.io)
+2. FlagDrop pushes a JSON config file to an S3 bucket in **your** AWS account
+3. The SDK reads that file and evaluates flags locally at runtime
+
+No network calls to FlagDrop servers during evaluation. No latency. No single point of failure.
+
+## Configuration
+
+| Parameter | Description |
+|-----------|-------------|
+| `bucket` | S3 bucket name where flag configs are stored |
+| `environment` | Environment name (e.g., `production`, `staging`) |
+| `provider` | Cloud provider (`aws`) |
+| `region` | AWS region (e.g., `us-east-1`) |
+| `scope` | Config scope: `backend` (default) or `frontend` |
+| `refresh_interval_seconds` | How often to re-fetch config (default: 30s, 0 to disable) |
+
+## Targeting Rules
+
+The SDK evaluates targeting rules locally. Supported operators:
+
+- `eq`, `neq` — exact match / not equal
+- `in`, `notIn` — value in list / not in list
+- `lt`, `gt` — less than / greater than (numeric)
+- `startsWith`, `endsWith`, `contains` — string matching
+- `segment` — segment membership
+
+## Rollouts
+
+Percentage-based rollouts use deterministic hashing, so the same user always gets the same result.
+
+## Requirements
+
+- Python 3.9+
+- `boto3` (AWS SDK)
+- AWS credentials with read access to your flag config bucket
+
+## Links
+
+- [FlagDrop](https://flagdrop.io) — Feature flags in your cloud
+- [Documentation](https://flagdrop.io/docs)

flagdrop_sdk-0.1.0/flagdrop/__init__.py

@@ -0,0 +1,10 @@
+from flagdrop.client import FlagClient
+from flagdrop.types import FlagClientConfig, UserContext, EvalResult, ConfigFile
+
+__all__ = [
+    "FlagClient",
+    "FlagClientConfig",
+    "UserContext",
+    "EvalResult",
+    "ConfigFile",
+]

flagdrop_sdk-0.1.0/flagdrop/client.py

@@ -0,0 +1,150 @@
+"""FlagDrop Python SDK client."""
+from __future__ import annotations
+
+import time
+from typing import Any, TypeVar
+
+from flagdrop.evaluator import evaluate_flag
+from flagdrop.providers import ConfigProvider, S3ConfigProvider
+from flagdrop.types import ConfigFile, FlagClientConfig, UserContext
+
+T = TypeVar("T")
+
+
+class FlagClient:
+    """
+    FlagDrop feature flag client.
+
+    Fetches config from your cloud bucket and evaluates flags locally.
+
+    Usage::
+
+        from flagdrop import FlagClient
+
+        client = FlagClient(
+            bucket="my-app-flags",
+            environment="production",
+            provider="aws",
+            region="us-east-1",
+        )
+        client.initialize()
+
+        enabled = client.get_bool("new-checkout", False)
+        theme = client.get_string("app-theme", "light", {"user_id": "user-123"})
+    """
+
+    def __init__(
+        self,
+        bucket: str,
+        environment: str,
+        provider: str,
+        region: str,
+        scope: str = "backend",
+        refresh_interval_seconds: float = 30,
+        config_provider: ConfigProvider | None = None,
+    ) -> None:
+        self._config = FlagClientConfig(
+            bucket=bucket,
+            environment=environment,
+            provider=provider,  # type: ignore[arg-type]
+            region=region,
+            scope=scope,
+            refresh_interval_seconds=refresh_interval_seconds,
+        )
+        self._cache: ConfigFile | None = None
+        self._last_fetched_at: float = 0
+
+        if config_provider is not None:
+            self._provider = config_provider
+        else:
+            self._provider = self._create_provider()
+
+    def _create_provider(self) -> ConfigProvider:
+        if self._config.provider == "aws":
+            return S3ConfigProvider(self._config.region)
+        elif self._config.provider in ("gcp", "azure"):
+            raise ValueError(
+                f"Provider '{self._config.provider}' is not yet supported. Use 'aws'."
+            )
+        else:
+            raise ValueError(f"Unknown provider: '{self._config.provider}'")
+
+    def _config_key(self) -> str:
+        return f"flags-{self._config.environment}-{self._config.scope}.json"
+
+    def _is_stale(self) -> bool:
+        if self._cache is None:
+            return True
+        if self._config.refresh_interval_seconds <= 0:
+            return False
+        return (
+            time.time() - self._last_fetched_at
+            > self._config.refresh_interval_seconds
+        )
+
+    def _load_config(self) -> ConfigFile:
+        if self._cache is not None and not self._is_stale():
+            return self._cache
+        self._cache = self._provider.fetch(self._config.bucket, self._config_key())
+        self._last_fetched_at = time.time()
+        return self._cache
+
+    def initialize(self) -> None:
+        """Fetch config from the bucket. Call this before evaluating flags."""
+        self._load_config()
+
+    def get_config(self) -> ConfigFile | None:
+        """Return cached config, or None if not yet loaded."""
+        return self._cache
+
+    def get_bool(
+        self,
+        flag_key: str,
+        default_value: bool,
+        context: UserContext | None = None,
+    ) -> bool:
+        config = self._load_config()
+        result = evaluate_flag(config, flag_key, context)
+        if not result.found or not result.enabled:
+            return default_value
+        return result.value if isinstance(result.value, bool) else default_value
+
+    def get_string(
+        self,
+        flag_key: str,
+        default_value: str,
+        context: UserContext | None = None,
+    ) -> str:
+        config = self._load_config()
+        result = evaluate_flag(config, flag_key, context)
+        if not result.found or not result.enabled:
+            return default_value
+        return result.value if isinstance(result.value, str) else default_value
+
+    def get_number(
+        self,
+        flag_key: str,
+        default_value: float,
+        context: UserContext | None = None,
+    ) -> float:
+        config = self._load_config()
+        result = evaluate_flag(config, flag_key, context)
+        if not result.found or not result.enabled:
+            return default_value
+        return (
+            result.value
+            if isinstance(result.value, (int, float))
+            else default_value
+        )
+
+    def get_json(
+        self,
+        flag_key: str,
+        default_value: T,
+        context: UserContext | None = None,
+    ) -> T:
+        config = self._load_config()
+        result = evaluate_flag(config, flag_key, context)
+        if not result.found or not result.enabled:
+            return default_value
+        return result.value  # type: ignore[return-value]

flagdrop_sdk-0.1.0/flagdrop/evaluator.py

@@ -0,0 +1,113 @@
+"""Flag evaluation engine — mirrors @flagdrop/evaluator from the Node.js SDK."""
+from __future__ import annotations
+
+from flagdrop.types import ConfigFile, EvalResult, Rule, UserContext
+
+
+def fnv1a_hash(input_str: str) -> int:
+    """FNV-1a 32-bit hash — deterministic bucketing."""
+    hash_val = 0x811C9DC5  # FNV offset basis
+    for ch in input_str:
+        hash_val ^= ord(ch)
+        hash_val = (hash_val * 0x01000193) & 0xFFFFFFFF  # FNV prime, mask to 32 bits
+    return hash_val
+
+
+def is_in_rollout(attribute_value: str, flag_key: str, percentage: float) -> bool:
+    """Deterministic percentage bucketing — same user always gets same result."""
+    if percentage <= 0:
+        return False
+    if percentage >= 100:
+        return True
+    hash_val = fnv1a_hash(flag_key + attribute_value)
+    bucket = hash_val % 100
+    return bucket < percentage
+
+
+def match_rule(rule: Rule, context: UserContext) -> bool:
+    """Evaluate a single targeting rule against user context."""
+    # Segment operator — check context["segments"] array
+    if rule.operator == "segment":
+        segments = context.get("segments")
+        if isinstance(segments, list):
+            return any(str(s) == str(rule.value) for s in segments)
+        return False
+
+    context_value = context.get(rule.attribute)
+
+    # Missing attribute — only neq/notIn match on absence
+    if context_value is None:
+        return rule.operator in ("neq", "notIn")
+
+    op = rule.operator
+
+    if op == "eq":
+        return str(context_value) == str(rule.value)
+    elif op == "neq":
+        return str(context_value) != str(rule.value)
+    elif op == "in":
+        values = rule.value if isinstance(rule.value, list) else []
+        return any(str(v) == str(context_value) for v in values)
+    elif op == "notIn":
+        values = rule.value if isinstance(rule.value, list) else []
+        return not any(str(v) == str(context_value) for v in values)
+    elif op == "lt":
+        try:
+            return float(context_value) < float(rule.value)
+        except (ValueError, TypeError):
+            return False
+    elif op == "gt":
+        try:
+            return float(context_value) > float(rule.value)
+        except (ValueError, TypeError):
+            return False
+    elif op == "startsWith":
+        return str(context_value).startswith(str(rule.value))
+    elif op == "endsWith":
+        return str(context_value).endswith(str(rule.value))
+    elif op == "contains":
+        return str(rule.value) in str(context_value)
+    else:
+        return False
+
+
+def evaluate_flag(
+    config: ConfigFile, flag_key: str, context: UserContext | None = None
+) -> EvalResult:
+    """
+    Evaluate a flag from a config file against optional user context.
+
+    Evaluation order:
+      1. Look up flag — if not found, return found=False
+      2. If disabled, return enabled=False with flag default
+      3. Rules evaluated in order — first match wins
+      4. Rollout check — deterministic hash bucketing
+      5. No match → return flag default with enabled=True
+    """
+    flag = config.flags.get(flag_key)
+
+    if flag is None:
+        return EvalResult(found=False, enabled=False, value=None)
+
+    if not flag.enabled:
+        return EvalResult(found=True, enabled=False, value=flag.default_value)
+
+    # Rules — first match wins
+    if flag.rules and context:
+        for rule in flag.rules:
+            if match_rule(rule, context):
+                return EvalResult(
+                    found=True,
+                    enabled=True,
+                    value=rule.serve_value,
+                    rule_match=rule.attribute,
+                )
+
+    # Rollout — deterministic percentage bucketing
+    if flag.rollout and context:
+        attr_value = context.get(flag.rollout.attribute)
+        if attr_value is not None:
+            if not is_in_rollout(str(attr_value), flag_key, flag.rollout.percentage):
+                return EvalResult(found=True, enabled=False, value=flag.default_value)
+
+    return EvalResult(found=True, enabled=True, value=flag.default_value)

flagdrop_sdk-0.1.0/flagdrop/providers.py

@@ -0,0 +1,35 @@
+"""Cloud storage providers for fetching flag config files."""
+from __future__ import annotations
+
+import json
+from typing import Protocol
+
+from flagdrop.types import ConfigFile
+
+
+class ConfigProvider(Protocol):
+    """Interface for fetching config from cloud storage."""
+
+    def fetch(self, bucket: str, key: str) -> ConfigFile: ...
+
+
+class S3ConfigProvider:
+    """Fetches flag config from AWS S3."""
+
+    def __init__(self, region: str) -> None:
+        self._region = region
+        self._client = None
+
+    def _get_client(self):
+        if self._client is None:
+            import boto3
+
+            self._client = boto3.client("s3", region_name=self._region)
+        return self._client
+
+    def fetch(self, bucket: str, key: str) -> ConfigFile:
+        client = self._get_client()
+        resp = client.get_object(Bucket=bucket, Key=key)
+        body = resp["Body"].read().decode("utf-8")
+        data = json.loads(body)
+        return ConfigFile.from_dict(data)

flagdrop_sdk-0.1.0/flagdrop/types.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+UserContext = dict[str, Any]
+
+
+@dataclass
+class Rule:
+    attribute: str
+    operator: str  # eq, neq, in, notIn, lt, gt, startsWith, endsWith, contains, segment
+    value: Any
+    serve_value: Any
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Rule:
+        return cls(
+            attribute=d.get("attribute", ""),
+            operator=d.get("operator", ""),
+            value=d.get("value"),
+            serve_value=d.get("serveValue"),
+        )
+
+
+@dataclass
+class Rollout:
+    percentage: float
+    attribute: str
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Rollout:
+        return cls(percentage=d.get("percentage", 0), attribute=d.get("attribute", ""))
+
+
+@dataclass
+class ConfigFlag:
+    type: str  # boolean, string, number, json
+    enabled: bool
+    default_value: Any
+    rules: list[Rule] = field(default_factory=list)
+    rollout: Rollout | None = None
+    description: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ConfigFlag:
+        rules = [Rule.from_dict(r) for r in (d.get("rules") or [])]
+        rollout_data = d.get("rollout")
+        rollout = Rollout.from_dict(rollout_data) if rollout_data else None
+        return cls(
+            type=d.get("type", "boolean"),
+            enabled=d.get("enabled", False),
+            default_value=d.get("defaultValue"),
+            rules=rules,
+            rollout=rollout,
+            description=d.get("description", ""),
+        )
+
+
+@dataclass
+class ConfigFile:
+    version: int
+    updated_at: str
+    scope: str
+    flags: dict[str, ConfigFlag]
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ConfigFile:
+        flags = {k: ConfigFlag.from_dict(v) for k, v in (d.get("flags") or {}).items()}
+        return cls(
+            version=d.get("version", 0),
+            updated_at=d.get("updatedAt", ""),
+            scope=d.get("scope", ""),
+            flags=flags,
+        )
+
+
+@dataclass
+class EvalResult:
+    found: bool
+    enabled: bool
+    value: Any
+    rule_match: str | None = None
+
+
+@dataclass
+class FlagClientConfig:
+    bucket: str
+    environment: str
+    provider: Literal["aws", "gcp", "azure"]
+    region: str
+    scope: str = "backend"
+    refresh_interval_seconds: float = 30

flagdrop_sdk-0.1.0/flagdrop_sdk.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: flagdrop-sdk
+Version: 0.1.0
+Summary: FlagDrop Python SDK — evaluate feature flags from your cloud bucket
+Author-email: FlagDrop <support@flagdrop.io>
+License: MIT
+Project-URL: Homepage, https://flagdrop.io
+Project-URL: Documentation, https://flagdrop.io/docs
+Keywords: feature-flags,flagdrop,sdk,s3,feature-toggles
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: boto3>=1.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: moto[s3]>=5.0; extra == "dev"
+
+# FlagDrop Python SDK
+
+Feature flag evaluation that runs entirely in your cloud. No vendor servers, no data leaving your infrastructure.
+
+## Installation
+
+```bash
+pip install flagdrop-sdk
+```
+
+## Quick Start
+
+```python
+from flagdrop import FlagClient
+
+client = FlagClient(
+    bucket="my-app-flags",
+    environment="production",
+    provider="aws",
+    region="us-east-1",
+)
+client.initialize()
+
+# Boolean flag
+enabled = client.get_bool("new-checkout", False)
+
+# String flag with targeting context
+theme = client.get_string("app-theme", "light", {"plan": "enterprise"})
+
+# Number flag
+max_items = client.get_number("max-items", 10)
+
+# JSON flag
+config = client.get_json("feature-config", {"limit": 5})
+```
+
+## How It Works
+
+1. You define flags in the [FlagDrop dashboard](https://flagdrop.io)
+2. FlagDrop pushes a JSON config file to an S3 bucket in **your** AWS account
+3. The SDK reads that file and evaluates flags locally at runtime
+
+No network calls to FlagDrop servers during evaluation. No latency. No single point of failure.
+
+## Configuration
+
+| Parameter | Description |
+|-----------|-------------|
+| `bucket` | S3 bucket name where flag configs are stored |
+| `environment` | Environment name (e.g., `production`, `staging`) |
+| `provider` | Cloud provider (`aws`) |
+| `region` | AWS region (e.g., `us-east-1`) |
+| `scope` | Config scope: `backend` (default) or `frontend` |
+| `refresh_interval_seconds` | How often to re-fetch config (default: 30s, 0 to disable) |
+
+## Targeting Rules
+
+The SDK evaluates targeting rules locally. Supported operators:
+
+- `eq`, `neq` — exact match / not equal
+- `in`, `notIn` — value in list / not in list
+- `lt`, `gt` — less than / greater than (numeric)
+- `startsWith`, `endsWith`, `contains` — string matching
+- `segment` — segment membership
+
+## Rollouts
+
+Percentage-based rollouts use deterministic hashing, so the same user always gets the same result.
+
+## Requirements
+
+- Python 3.9+
+- `boto3` (AWS SDK)
+- AWS credentials with read access to your flag config bucket
+
+## Links
+
+- [FlagDrop](https://flagdrop.io) — Feature flags in your cloud
+- [Documentation](https://flagdrop.io/docs)