switchbox-flags 0.1.0__py3-none-any.whl

switchbox/__init__.py

@@ -0,0 +1,5 @@
+from switchbox.client import Client
+from switchbox.exceptions import SwitchboxError
+
+__version__ = "0.1.0"
+__all__ = ["Client", "SwitchboxError"]

switchbox/cache.py

@@ -0,0 +1,31 @@
+import threading
+
+from switchbox.models import Flag, FlagConfig
+
+
+class FlagCache:
+    """Thread-safe in-memory store for flag configs."""
+
+    def __init__(self) -> None:
+        self._config: FlagConfig | None = None
+        self._lock = threading.Lock()
+
+    def get_config(self) -> FlagConfig | None:
+        with self._lock:
+            return self._config
+
+    def set_config(self, config: FlagConfig) -> None:
+        with self._lock:
+            self._config = config
+
+    def get_flag(self, key: str) -> Flag | None:
+        with self._lock:
+            if self._config is None:
+                return None
+            return self._config.flags.get(key)
+
+    def get_version(self) -> str | None:
+        with self._lock:
+            if self._config is None:
+                return None
+            return self._config.version

switchbox/client.py

@@ -0,0 +1,75 @@
+from typing import Any, Callable
+
+from switchbox.cache import FlagCache
+from switchbox.evaluator import evaluate
+from switchbox.sync import SyncWorker
+
+
+class Client:
+    """Switchbox feature flag client.
+
+    Fetches flag configs from a CDN and evaluates them locally.
+
+    Usage::
+
+        client = Client(cdn_url="https://cdn.example.com/proj/production/flags.json")
+        if client.enabled("new_feature", user={"user_id": "42"}):
+            ...
+        client.close()
+
+    Or as a context manager::
+
+        with Client(cdn_url="...") as client:
+            if client.enabled("new_feature"):
+                ...
+    """
+
+    def __init__(
+        self,
+        cdn_url: str,
+        poll_interval: int = 30,
+        on_error: Callable[[Exception], None] | None = None,
+    ) -> None:
+        self._cache = FlagCache()
+        self._sync = SyncWorker(cdn_url, self._cache, poll_interval, on_error)
+        self._sync.start()
+
+    def enabled(self, flag_key: str, user: dict | None = None) -> bool:
+        """Check if a boolean flag is enabled for a user.
+
+        Returns False if the flag doesn't exist (safe default).
+        """
+        flag = self._cache.get_flag(flag_key)
+        if flag is None:
+            return False
+        result = evaluate(flag, user)
+        return bool(result)
+
+    def get_value(
+        self, flag_key: str, user: dict | None = None, default: Any = None
+    ) -> Any:
+        """Get the resolved value of any flag type.
+
+        Returns *default* if the flag doesn't exist.
+        """
+        flag = self._cache.get_flag(flag_key)
+        if flag is None:
+            return default
+        return evaluate(flag, user)
+
+    def get_all_flags(self, user: dict | None = None) -> dict[str, Any]:
+        """Get all flag values resolved for a user."""
+        config = self._cache.get_config()
+        if config is None:
+            return {}
+        return {key: evaluate(flag, user) for key, flag in config.flags.items()}
+
+    def close(self) -> None:
+        """Stop the background sync. Call on shutdown."""
+        self._sync.stop()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

switchbox/evaluator.py

@@ -0,0 +1,98 @@
+"""Pure evaluation engine for Switchbox feature flags.
+
+Zero external dependencies — only Python stdlib.
+"""
+
+import hashlib
+from typing import Any
+
+from switchbox.models import Flag, Rule
+
+
+def evaluate(flag: Flag, user_context: dict | None = None) -> bool | str | int | Any:
+    """Evaluate a flag for a given user context.
+
+    Returns the flag's resolved value.
+
+    Evaluation order:
+    1. Flag disabled → default_value
+    2. No user context → enabled value if rollout == 100, else default_value
+    3. Rules match (OR logic) → enabled value
+    4. Rollout percentage check → enabled value or default_value
+    5. Nothing matched → default_value
+    """
+    # 1. Disabled flag always returns default
+    if not flag.enabled:
+        return flag.default_value
+
+    # 2. No user context
+    if not user_context:
+        if flag.rollout_pct == 100:
+            return _enabled_value(flag)
+        return flag.default_value
+
+    # 3. Check rules (OR logic — any match wins)
+    if flag.rules:
+        for rule in flag.rules:
+            if _match_rule(rule, user_context):
+                return _enabled_value(flag)
+
+    # 4. Rollout percentage
+    user_id = user_context.get("user_id") or user_context.get("id")
+    if user_id is not None:
+        if _check_rollout(str(user_id), flag.key, flag.rollout_pct):
+            return _enabled_value(flag)
+    else:
+        # No user ID for hashing — can only serve 100% rollouts
+        if flag.rollout_pct == 100:
+            return _enabled_value(flag)
+        return flag.default_value
+
+    # 5. Nothing matched
+    return flag.default_value
+
+
+def _enabled_value(flag: Flag) -> bool | str | int | Any:
+    """Return the appropriate 'enabled' value based on flag type."""
+    if flag.flag_type == "boolean":
+        return True
+    return flag.default_value
+
+
+def _match_rule(rule: Rule, user_context: dict) -> bool:
+    """Check if a single rule matches the user context."""
+    if rule.attribute not in user_context:
+        return False
+
+    context_value = user_context[rule.attribute]
+
+    if rule.operator == "equals":
+        return str(context_value) == str(rule.value)
+    elif rule.operator == "not_equals":
+        return str(context_value) != str(rule.value)
+    elif rule.operator == "contains":
+        return str(rule.value) in str(context_value)
+    elif rule.operator == "ends_with":
+        return str(context_value).endswith(str(rule.value))
+    elif rule.operator == "in_list":
+        return str(context_value) in rule.value
+    elif rule.operator == "gt":
+        try:
+            return float(context_value) > float(rule.value)
+        except (ValueError, TypeError):
+            return False
+    elif rule.operator == "lt":
+        try:
+            return float(context_value) < float(rule.value)
+        except (ValueError, TypeError):
+            return False
+
+    return False
+
+
+def _check_rollout(user_id: str, flag_key: str, rollout_pct: int) -> bool:
+    """Deterministic percentage rollout using consistent hashing."""
+    hash_input = f"{user_id}:{flag_key}"
+    hash_value = int(hashlib.sha256(hash_input.encode()).hexdigest(), 16)
+    bucket = hash_value % 100
+    return bucket < rollout_pct

switchbox/exceptions.py

@@ -0,0 +1,10 @@
+class SwitchboxError(Exception):
+    """Base exception for Switchbox SDK."""
+
+
+class ConfigFetchError(SwitchboxError):
+    """Raised when fetching flag config from CDN fails."""
+
+
+class EvaluationError(SwitchboxError):
+    """Raised when flag evaluation encounters an error."""

switchbox/models.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Rule:
+    attribute: str
+    operator: str  # equals | not_equals | contains | ends_with | in_list | gt | lt
+    value: Any
+
+
+@dataclass
+class Flag:
+    key: str
+    enabled: bool
+    rollout_pct: int
+    flag_type: str  # boolean | string | number | json
+    default_value: Any
+    rules: list[Rule] = field(default_factory=list)
+
+
+@dataclass
+class FlagConfig:
+    version: str  # ISO timestamp
+    flags: dict[str, Flag] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> FlagConfig:
+        """Parse the CDN JSON into a FlagConfig object."""
+        flags = {}
+        for key, flag_data in data.get("flags", {}).items():
+            rules = [
+                Rule(
+                    attribute=r["attribute"],
+                    operator=r["operator"],
+                    value=r["value"],
+                )
+                for r in flag_data.get("rules", [])
+            ]
+            flags[key] = Flag(
+                key=key,
+                enabled=flag_data["enabled"],
+                rollout_pct=flag_data.get("rollout_pct", 0),
+                flag_type=flag_data.get("flag_type", "boolean"),
+                default_value=flag_data.get("default_value"),
+                rules=rules,
+            )
+        return cls(version=data.get("version", ""), flags=flags)

switchbox/sync.py

@@ -0,0 +1,76 @@
+import json
+import logging
+import threading
+import urllib.request
+from typing import Callable
+
+from switchbox.cache import FlagCache
+from switchbox.exceptions import ConfigFetchError
+from switchbox.models import FlagConfig
+
+logger = logging.getLogger("switchbox")
+
+
+class SyncWorker:
+    """Background thread that polls the CDN for updated flag configs."""
+
+    def __init__(
+        self,
+        cdn_url: str,
+        cache: FlagCache,
+        interval: int = 30,
+        on_error: Callable[[Exception], None] | None = None,
+    ) -> None:
+        self._cdn_url = cdn_url
+        self._cache = cache
+        self._interval = interval
+        self._on_error = on_error
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        """Fetch configs synchronously first, then start background polling."""
+        # Initial synchronous fetch — block until we have configs
+        self._poll()
+
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the background polling thread gracefully."""
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join(timeout=5)
+
+    def _run(self) -> None:
+        """Main loop for the background thread."""
+        while not self._stop_event.wait(timeout=self._interval):
+            self._poll()
+
+    def _poll(self) -> None:
+        """Fetch config from CDN, parse, and update cache if changed."""
+        try:
+            req = urllib.request.Request(
+                self._cdn_url,
+                headers={"User-Agent": "switchbox-python/0.1.0"},
+            )
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+
+            # Skip parsing if version hasn't changed
+            new_version = data.get("version", "")
+            current_version = self._cache.get_version()
+            if current_version and new_version == current_version:
+                return
+
+            config = FlagConfig.from_dict(data)
+            self._cache.set_config(config)
+            logger.debug("Updated flag config to version %s", config.version)
+
+        except Exception as exc:
+            logger.warning("Failed to fetch flag config from %s: %s", self._cdn_url, exc)
+            if self._on_error is not None:
+                try:
+                    self._on_error(ConfigFetchError(str(exc)))
+                except Exception:
+                    pass

switchbox_flags-0.1.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: switchbox-flags
+Version: 0.1.0
+Summary: Feature flag SDK with zero dependencies
+Project-URL: Homepage, https://github.com/ignat14/switchbox-sdk-python
+Project-URL: Repository, https://github.com/ignat14/switchbox-sdk-python
+Project-URL: Issues, https://github.com/ignat14/switchbox-sdk-python/issues
+Author: Switchbox
+License-Expression: MIT
+License-File: LICENSE
+Keywords: feature-flags,feature-toggles,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Switchbox
+
+Feature flag SDK for Python. Zero dependencies. Reads configs from a CDN.
+
+## Install
+
+```
+pip install switchbox-flags
+```
+
+## Quick start
+
+```python
+from switchbox import Client
+
+client = Client(cdn_url="https://your-cdn.r2.dev/project_id/production/flags.json")
+
+# Boolean flag
+if client.enabled("new_checkout", user={"user_id": "42", "email": "a@b.com"}):
+    show_new_checkout()
+
+# String flag
+version = client.get_value("search_version", user={"user_id": "42"}, default="v1")
+
+# All flags at once
+flags = client.get_all_flags(user={"user_id": "42"})
+
+# Cleanup
+client.close()
+```
+
+Or use as a context manager:
+
+```python
+with Client(cdn_url="https://your-cdn.r2.dev/project_id/production/flags.json") as client:
+    if client.enabled("new_checkout", user={"user_id": "42"}):
+        show_new_checkout()
+```
+
+## How it works
+
+- Fetches flag configs from CDN (static JSON, no server in the loop)
+- Evaluates rules locally (sub-millisecond)
+- Polls for updates every 30 seconds (configurable)
+- Works offline — keeps using cached configs if CDN is unreachable
+- Zero runtime dependencies — only Python stdlib
+
+## Configuration
+
+```python
+client = Client(
+    cdn_url="https://your-cdn.r2.dev/project_id/production/flags.json",
+    poll_interval=60,          # poll every 60 seconds (default: 30)
+    on_error=lambda e: print(e),  # optional error callback
+)
+```
+
+## Evaluation logic
+
+1. **Disabled flag** — returns `default_value`
+2. **Rules** — if any rule matches the user context (OR logic), the flag is on
+3. **Rollout** — deterministic percentage based on `sha256(user_id:flag_key)`
+4. **Fallback** — returns `default_value`
+
+## License
+
+MIT

switchbox_flags-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+switchbox/__init__.py,sha256=euy9_hMMg70MENnhWb5cKNyusiXCGZmc2d08QsMjSAs,146
+switchbox/cache.py,sha256=WmeKkQSiVrOtZh_psou6qXibSL82nQJw7jxNfqTXT5E,835
+switchbox/client.py,sha256=GISyZaYOPNJkxXKVkapn9AwZz0bTMfvyFLvqhebatz0,2202
+switchbox/evaluator.py,sha256=Xuo5ybTfHvytouuIIoor9Q6HVPGbCFIhknaFXnq663k,3194
+switchbox/exceptions.py,sha256=Vv5YMiqh9gdEztXX9gGvvl721xV7f3Gzk2TcHS8WEwY,278
+switchbox/models.py,sha256=xdKvg6fOrtwdh45nGsxm8w9M81W8W4A9klcYeKXNgjM,1397
+switchbox/sync.py,sha256=Vzx8YdMydjDUujL-Gw7--xHOu0p25FqFsh3MshgP6b4,2565
+switchbox_flags-0.1.0.dist-info/METADATA,sha256=913axQyjtRBPJS-0fi1KOod4eobZh19gxa39OH77vmQ,2543
+switchbox_flags-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+switchbox_flags-0.1.0.dist-info/licenses/LICENSE,sha256=wcGGHspwJcuwpobuEkium65D2JZax2cUwEpT1V7nPCs,1066
+switchbox_flags-0.1.0.dist-info/RECORD,,

switchbox_flags-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

switchbox_flags-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Switchbox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.