switchbox-flags 0.1.0__tar.gz

switchbox_flags-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

switchbox_flags-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest -v

switchbox_flags-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+.env
+*.so
+.DS_Store

switchbox_flags-0.1.0/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.

switchbox_flags-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,67 @@
+# 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/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "switchbox-flags"
+version = "0.1.0"
+description = "Feature flag SDK with zero dependencies"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+authors = [{ name = "Switchbox" }]
+keywords = ["feature-flags", "feature-toggles", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/ignat14/switchbox-sdk-python"
+Repository = "https://github.com/ignat14/switchbox-sdk-python"
+Issues = "https://github.com/ignat14/switchbox-sdk-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["switchbox"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.4"]

switchbox_flags-0.1.0/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_flags-0.1.0/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_flags-0.1.0/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_flags-0.1.0/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_flags-0.1.0/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_flags-0.1.0/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_flags-0.1.0/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/tests/test_cache.py

@@ -0,0 +1,81 @@
+import threading
+
+from switchbox.cache import FlagCache
+from switchbox.models import Flag, FlagConfig
+
+
+def _make_config(version="v1"):
+    return FlagConfig(
+        version=version,
+        flags={
+            "flag_a": Flag(
+                key="flag_a",
+                enabled=True,
+                rollout_pct=100,
+                flag_type="boolean",
+                default_value=False,
+                rules=[],
+            ),
+        },
+    )
+
+
+def test_cache_starts_empty():
+    cache = FlagCache()
+    assert cache.get_config() is None
+    assert cache.get_version() is None
+    assert cache.get_flag("anything") is None
+
+
+def test_set_and_get_config():
+    cache = FlagCache()
+    config = _make_config()
+    cache.set_config(config)
+    assert cache.get_config() is config
+    assert cache.get_version() == "v1"
+
+
+def test_get_flag_returns_correct_flag():
+    cache = FlagCache()
+    cache.set_config(_make_config())
+    flag = cache.get_flag("flag_a")
+    assert flag is not None
+    assert flag.key == "flag_a"
+
+
+def test_get_flag_returns_none_for_missing_key():
+    cache = FlagCache()
+    cache.set_config(_make_config())
+    assert cache.get_flag("nonexistent") is None
+
+
+def test_thread_safety():
+    """Concurrent reads and writes should not raise or corrupt data."""
+    cache = FlagCache()
+    errors = []
+
+    def writer():
+        try:
+            for i in range(200):
+                cache.set_config(_make_config(version=f"v{i}"))
+        except Exception as e:
+            errors.append(e)
+
+    def reader():
+        try:
+            for _ in range(200):
+                cache.get_config()
+                cache.get_flag("flag_a")
+                cache.get_version()
+        except Exception as e:
+            errors.append(e)
+
+    threads = [threading.Thread(target=writer) for _ in range(4)]
+    threads += [threading.Thread(target=reader) for _ in range(4)]
+
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+
+    assert errors == []

switchbox_flags-0.1.0/tests/test_client.py

@@ -0,0 +1,64 @@
+import json
+from unittest.mock import MagicMock, patch
+
+from switchbox.client import Client
+
+SAMPLE_CONFIG = {
+    "version": "2026-04-07T12:00:00Z",
+    "flags": {
+        "new_dashboard": {
+            "enabled": True,
+            "rollout_pct": 100,
+            "flag_type": "boolean",
+            "default_value": False,
+            "rules": [],
+        },
+        "search_version": {
+            "enabled": True,
+            "rollout_pct": 100,
+            "flag_type": "string",
+            "default_value": "v1",
+            "rules": [],
+        },
+    },
+}
+
+
+def _mock_urlopen(data):
+    """Create a mock that mimics urllib.request.urlopen response."""
+    resp = MagicMock()
+    resp.read.return_value = json.dumps(data).encode("utf-8")
+    resp.__enter__ = lambda s: s
+    resp.__exit__ = MagicMock(return_value=False)
+    return resp
+
+
+@patch("switchbox.sync.urllib.request.urlopen")
+def test_client_returns_false_for_nonexistent_flag(mock_urlopen):
+    mock_urlopen.return_value = _mock_urlopen(SAMPLE_CONFIG)
+    with Client(cdn_url="https://example.com/flags.json") as client:
+        assert client.enabled("nonexistent") is False
+
+
+@patch("switchbox.sync.urllib.request.urlopen")
+def test_client_get_value_returns_default_for_nonexistent_flag(mock_urlopen):
+    mock_urlopen.return_value = _mock_urlopen(SAMPLE_CONFIG)
+    with Client(cdn_url="https://example.com/flags.json") as client:
+        assert client.get_value("nonexistent", default="fallback") == "fallback"
+
+
+@patch("switchbox.sync.urllib.request.urlopen")
+def test_client_works_with_mock_cdn(mock_urlopen):
+    mock_urlopen.return_value = _mock_urlopen(SAMPLE_CONFIG)
+    with Client(cdn_url="https://example.com/flags.json") as client:
+        assert client.enabled("new_dashboard", user={"user_id": "1"}) is True
+        assert client.get_value("search_version", user={"user_id": "1"}) == "v1"
+
+
+@patch("switchbox.sync.urllib.request.urlopen")
+def test_client_handles_cdn_failure_gracefully(mock_urlopen):
+    mock_urlopen.side_effect = Exception("Network error")
+    with Client(cdn_url="https://example.com/flags.json") as client:
+        # Should return safe defaults, not crash
+        assert client.enabled("new_dashboard") is False
+        assert client.get_value("search_version", default="v1") == "v1"

switchbox_flags-0.1.0/tests/test_evaluator.py

@@ -0,0 +1,144 @@
+from switchbox.evaluator import _check_rollout, _match_rule, evaluate
+from switchbox.models import Flag, Rule
+
+
+def make_flag(
+    key="test_flag",
+    enabled=True,
+    rollout_pct=100,
+    flag_type="boolean",
+    default_value=False,
+    rules=None,
+):
+    return Flag(
+        key=key,
+        enabled=enabled,
+        rollout_pct=rollout_pct,
+        flag_type=flag_type,
+        default_value=default_value,
+        rules=rules or [],
+    )
+
+
+# --- Basic evaluation ---
+
+
+def test_disabled_flag_returns_default():
+    flag = make_flag(enabled=False, default_value="off")
+    assert evaluate(flag, {"user_id": "1"}) == "off"
+
+
+def test_enabled_flag_100_rollout_returns_true():
+    flag = make_flag(enabled=True, rollout_pct=100)
+    assert evaluate(flag, {"user_id": "1"}) is True
+
+
+def test_enabled_flag_0_rollout_returns_default():
+    flag = make_flag(enabled=True, rollout_pct=0, default_value=False)
+    assert evaluate(flag, {"user_id": "1"}) is False
+
+
+# --- Rule matching operators ---
+
+
+def test_rule_equals():
+    rule = Rule(attribute="country", operator="equals", value="US")
+    assert _match_rule(rule, {"country": "US"}) is True
+    assert _match_rule(rule, {"country": "UK"}) is False
+
+
+def test_rule_not_equals():
+    rule = Rule(attribute="country", operator="not_equals", value="US")
+    assert _match_rule(rule, {"country": "UK"}) is True
+    assert _match_rule(rule, {"country": "US"}) is False
+
+
+def test_rule_contains():
+    rule = Rule(attribute="email", operator="contains", value="@company")
+    assert _match_rule(rule, {"email": "alice@company.com"}) is True
+    assert _match_rule(rule, {"email": "alice@other.com"}) is False
+
+
+def test_rule_ends_with():
+    rule = Rule(attribute="email", operator="ends_with", value="@company.com")
+    assert _match_rule(rule, {"email": "alice@company.com"}) is True
+    assert _match_rule(rule, {"email": "alice@other.com"}) is False
+
+
+def test_rule_in_list():
+    rule = Rule(attribute="tier", operator="in_list", value=["gold", "platinum"])
+    assert _match_rule(rule, {"tier": "gold"}) is True
+    assert _match_rule(rule, {"tier": "silver"}) is False
+
+
+def test_rule_gt():
+    rule = Rule(attribute="age", operator="gt", value="18")
+    assert _match_rule(rule, {"age": 21}) is True
+    assert _match_rule(rule, {"age": 16}) is False
+
+
+def test_rule_lt():
+    rule = Rule(attribute="age", operator="lt", value="18")
+    assert _match_rule(rule, {"age": 16}) is True
+    assert _match_rule(rule, {"age": 21}) is False
+
+
+def test_rule_missing_attribute_does_not_match():
+    rule = Rule(attribute="country", operator="equals", value="US")
+    assert _match_rule(rule, {"email": "a@b.com"}) is False
+
+
+# --- Rules in evaluation (OR logic) ---
+
+
+def test_any_rule_match_returns_enabled():
+    flag = make_flag(
+        rollout_pct=0,
+        rules=[
+            Rule(attribute="country", operator="equals", value="US"),
+            Rule(attribute="email", operator="ends_with", value="@company.com"),
+        ],
+    )
+    # Second rule matches
+    assert evaluate(flag, {"user_id": "1", "email": "a@company.com"}) is True
+
+
+# --- Rollout ---
+
+
+def test_rollout_deterministic():
+    """Same user + flag always yields the same result."""
+    results = [_check_rollout("user42", "flag_a", 50) for _ in range(100)]
+    assert len(set(results)) == 1
+
+
+def test_rollout_distribution():
+    """Over 10k users, ~30% should be in a 30% rollout (within tolerance)."""
+    in_rollout = sum(_check_rollout(str(i), "flag_b", 30) for i in range(10_000))
+    assert 2500 < in_rollout < 3500
+
+
+# --- No user context ---
+
+
+def test_no_user_context_100_rollout():
+    flag = make_flag(rollout_pct=100)
+    assert evaluate(flag, None) is True
+
+
+def test_no_user_context_partial_rollout_returns_default():
+    flag = make_flag(rollout_pct=50, default_value=False)
+    assert evaluate(flag, None) is False
+
+
+# --- Non-boolean flag types ---
+
+
+def test_string_flag_returns_string_value():
+    flag = make_flag(flag_type="string", default_value="v1", rollout_pct=100)
+    assert evaluate(flag, {"user_id": "1"}) == "v1"
+
+
+def test_number_flag_returns_number_value():
+    flag = make_flag(flag_type="number", default_value=42, rollout_pct=100)
+    assert evaluate(flag, {"user_id": "1"}) == 42