switchbox-flags 0.2.0__tar.gz → 0.3.0__tar.gz

{switchbox_flags-0.2.0 → switchbox_flags-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: switchbox-flags
-Version: 0.2.0
+Version: 0.3.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
@@ -45,9 +45,9 @@ pip install switchbox-flags
 ## Quick Start
 
 ```python
-from switchbox import Client
+from switchbox import Switchbox
 
-client = Client(sdk_key="your-sdk-key-from-dashboard")
+client = Switchbox(sdk_key="your-sdk-key-from-dashboard")
 
 if client.enabled("new_checkout", user={"user_id": "42"}):
     show_new_checkout()
@@ -63,16 +63,16 @@ client.close()
 - **Background polling** — syncs configs every 30 seconds (configurable)
 - **Offline resilient** — keeps working on cached configs if the CDN is unreachable
 - **Thread-safe** — safe to use from multiple threads
-- **Context manager** — supports `with Client(...) as client:` for automatic cleanup
+- **Context manager** — supports `with Switchbox(...) as client:` for automatic cleanup
 
 ## Usage
 
 ### Boolean Flags
 
 ```python
-from switchbox import Client
+from switchbox import Switchbox
 
-client = Client(sdk_key="your-sdk-key-from-dashboard")
+client = Switchbox(sdk_key="your-sdk-key-from-dashboard")
 
 if client.enabled("dark_mode"):
     enable_dark_mode()
@@ -142,7 +142,7 @@ If the SDK has never successfully fetched a config (e.g., CDN is down on first s
 ### Context Manager
 
 ```python
-with Client(sdk_key="your-sdk-key-from-dashboard") as client:
+with Switchbox(sdk_key="your-sdk-key-from-dashboard") as client:
     if client.enabled("new_checkout", user={"user_id": "42"}):
         show_new_checkout()
 # client.close() is called automatically
@@ -151,7 +151,7 @@ with Client(sdk_key="your-sdk-key-from-dashboard") as client:
 ## Configuration
 
 ```python
-client = Client(
+client = Switchbox(
     sdk_key="your-sdk-key-from-dashboard",  # required — get from Environments tab
     poll_interval=60,                       # seconds between polls (default: 30)
     on_error=lambda e: logger.warning(e),   # called on fetch errors (default: None)
@@ -198,7 +198,7 @@ The API server is only in the write path. All read traffic goes to the CDN.
 
 ## API Reference
 
-### `Client(sdk_key, poll_interval=30, on_error=None)`
+### `Switchbox(sdk_key, poll_interval=30, on_error=None)`
 
 Creates a new client. Performs an initial synchronous fetch on creation, then starts background polling.
 

{switchbox_flags-0.2.0 → switchbox_flags-0.3.0}/README.md

@@ -19,9 +19,9 @@ pip install switchbox-flags
 ## Quick Start
 
 ```python
-from switchbox import Client
+from switchbox import Switchbox
 
-client = Client(sdk_key="your-sdk-key-from-dashboard")
+client = Switchbox(sdk_key="your-sdk-key-from-dashboard")
 
 if client.enabled("new_checkout", user={"user_id": "42"}):
     show_new_checkout()
@@ -37,16 +37,16 @@ client.close()
 - **Background polling** — syncs configs every 30 seconds (configurable)
 - **Offline resilient** — keeps working on cached configs if the CDN is unreachable
 - **Thread-safe** — safe to use from multiple threads
-- **Context manager** — supports `with Client(...) as client:` for automatic cleanup
+- **Context manager** — supports `with Switchbox(...) as client:` for automatic cleanup
 
 ## Usage
 
 ### Boolean Flags
 
 ```python
-from switchbox import Client
+from switchbox import Switchbox
 
-client = Client(sdk_key="your-sdk-key-from-dashboard")
+client = Switchbox(sdk_key="your-sdk-key-from-dashboard")
 
 if client.enabled("dark_mode"):
     enable_dark_mode()
@@ -116,7 +116,7 @@ If the SDK has never successfully fetched a config (e.g., CDN is down on first s
 ### Context Manager
 
 ```python
-with Client(sdk_key="your-sdk-key-from-dashboard") as client:
+with Switchbox(sdk_key="your-sdk-key-from-dashboard") as client:
     if client.enabled("new_checkout", user={"user_id": "42"}):
         show_new_checkout()
 # client.close() is called automatically
@@ -125,7 +125,7 @@ with Client(sdk_key="your-sdk-key-from-dashboard") as client:
 ## Configuration
 
 ```python
-client = Client(
+client = Switchbox(
     sdk_key="your-sdk-key-from-dashboard",  # required — get from Environments tab
     poll_interval=60,                       # seconds between polls (default: 30)
     on_error=lambda e: logger.warning(e),   # called on fetch errors (default: None)
@@ -172,7 +172,7 @@ The API server is only in the write path. All read traffic goes to the CDN.
 
 ## API Reference
 
-### `Client(sdk_key, poll_interval=30, on_error=None)`
+### `Switchbox(sdk_key, poll_interval=30, on_error=None)`
 
 Creates a new client. Performs an initial synchronous fetch on creation, then starts background polling.
 

{switchbox_flags-0.2.0 → switchbox_flags-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "switchbox-flags"
-version = "0.2.0"
+version = "0.3.0"
 description = "Feature flag SDK with zero dependencies"
 readme = "README.md"
 license = "MIT"

switchbox_flags-0.3.0/switchbox/__init__.py

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

{switchbox_flags-0.2.0 → switchbox_flags-0.3.0}/switchbox/client.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from typing import Any, Callable
 
 from switchbox.cache import FlagCache
@@ -7,21 +9,21 @@ from switchbox.sync import SyncWorker
 CDN_BASE_URL = "https://cdn.switchbox.dev"
 
 
-class Client:
+class Switchbox:
     """Switchbox feature flag client.
 
     Fetches flag configs from a CDN and evaluates them locally.
 
     Usage::
 
-        client = Client(sdk_key="your-sdk-key")
+        client = Switchbox(sdk_key="your-sdk-key")
         if client.enabled("new_feature", user={"user_id": "42"}):
             ...
         client.close()
 
     Or as a context manager::
 
-        with Client(sdk_key="your-sdk-key") as client:
+        with Switchbox(sdk_key="your-sdk-key") as client:
             if client.enabled("new_feature"):
                 ...
     """
@@ -45,16 +47,23 @@ class Client:
         """Return True when configs have been loaded at least once."""
         return self._cache.get_config() is not None
 
+    def _eval_flag(self, flag_key: str, user: dict | None, fallback: Any) -> Any:
+        """Look up a flag and evaluate it, returning *fallback* if it's absent.
+
+        The shared path behind enabled()/get_value() — they differ only in
+        their fallback and how they coerce the result.
+        """
+        flag = self._cache.get_flag(flag_key)
+        if flag is None:
+            return fallback
+        return evaluate(flag, user)
+
     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)
+        return bool(self._eval_flag(flag_key, user, False))
 
     def get_value(
         self, flag_key: str, user: dict | None = None, default: Any = None
@@ -63,10 +72,7 @@ class Client:
 
         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)
+        return self._eval_flag(flag_key, user, default)
 
     def get_all_flags(self, user: dict | None = None) -> dict[str, Any]:
         """Get all flag values resolved for a user."""
@@ -79,7 +85,7 @@ class Client:
         """Stop the background sync. Call on shutdown."""
         self._sync.stop()
 
-    def __enter__(self) -> Client:
+    def __enter__(self) -> Switchbox:
         return self
 
     def __exit__(self, *args: object) -> None:

switchbox_flags-0.3.0/switchbox/evaluator.py

@@ -0,0 +1,135 @@
+"""Pure evaluation engine for Switchbox feature flags.
+
+Zero external dependencies — only Python stdlib.
+"""
+
+import hashlib
+import re
+from typing import Any
+
+from switchbox.models import Flag, Rule
+
+# Leading numeric prefix, matching JS parseFloat (e.g. "25px" -> 25, "1e3" -> 1000).
+_NUMERIC_PREFIX = re.compile(r"[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?")
+
+
+def _js_str(value: Any) -> str:
+    """Coerce a value to a string the way JavaScript's String() does — the
+    canonical coercion for cross-SDK rule parity (SEC-4, ADR-013):
+
+    - booleans are lowercase ("true"/"false"), not Python's "True"/"False"
+    - None becomes "null"
+    - an integer-valued float drops its trailing ".0" (JS has no int/float split)
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if value is None:
+        return "null"
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    return str(value)
+
+
+def _to_number(value: Any) -> float | None:
+    """Mimic JS parseFloat(String(value)): parse a leading numeric prefix, or
+    return None (JS NaN) when there isn't one. Booleans are NaN, matching
+    parseFloat("true")."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    match = _NUMERIC_PREFIX.match(str(value).lstrip())
+    return float(match.group(0)) if match else None
+
+
+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
+    """
+    try:
+        # 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. Resolve the id with a null-only fallback (JS `??`, not
+        # `or`): an empty-string user_id is a real id, not falsy.
+        user_id = user_context.get("user_id")
+        if user_id is None:
+            user_id = user_context.get("id")
+        if user_id is not None:
+            in_bucket = _check_rollout(_js_str(user_id), flag.key, flag.rollout_pct)
+            return _enabled_value(flag) if in_bucket else flag.default_value
+
+        # 5. No usable id to hash → only a full (100%) rollout reaches everyone
+        # (matches the no-user-context branch above; ADR-008).
+        return _enabled_value(flag) if flag.rollout_pct == 100 else flag.default_value
+    except Exception:
+        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.
+
+    All string comparisons coerce via _js_str (so `equals "true"` matches a
+    boolean True, and a None value coerces to "null" rather than never matching
+    — matching the JS SDK). gt/lt parse a leading numeric prefix like
+    parseFloat. See SEC-4 / ADR-013.
+    """
+    if rule.attribute not in user_context:
+        return False
+
+    context_value = user_context[rule.attribute]
+
+    if rule.operator == "equals":
+        return _js_str(context_value) == _js_str(rule.value)
+    elif rule.operator == "not_equals":
+        return _js_str(context_value) != _js_str(rule.value)
+    elif rule.operator == "contains":
+        return _js_str(rule.value) in _js_str(context_value)
+    elif rule.operator == "ends_with":
+        return _js_str(context_value).endswith(_js_str(rule.value))
+    elif rule.operator == "in_list":
+        return _js_str(context_value) in rule.value
+    elif rule.operator == "gt":
+        a, b = _to_number(context_value), _to_number(rule.value)
+        return a is not None and b is not None and a > b
+    elif rule.operator == "lt":
+        a, b = _to_number(context_value), _to_number(rule.value)
+        return a is not None and b is not None and a < b
+
+    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.2.0 → switchbox_flags-0.3.0}/switchbox/models.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from dataclasses import dataclass, field
 from typing import Any
 

{switchbox_flags-0.2.0 → switchbox_flags-0.3.0}/switchbox/sync.py

@@ -58,7 +58,7 @@ class SyncWorker:
         try:
             req = urllib.request.Request(
                 self._cdn_url,
-                headers={"User-Agent": "switchbox-python/0.1.0"},
+                headers={"User-Agent": "switchbox-python/0.3.0"},
             )
             with urllib.request.urlopen(req, timeout=self._timeout) as resp:
                 data = json.loads(resp.read().decode("utf-8"))

switchbox_flags-0.3.0/tests/parity_vectors.json

@@ -0,0 +1,33 @@
+{
+  "_comment": "SEC-4 cross-SDK parity vectors. This file MUST be byte-identical to switchbox-sdk-js/packages/core/tests/parity_vectors.json — it is duplicated into each repo because each SDK is built/tested by its own CI. Canonical semantics are JS-style: lowercase booleans (String(true)='true'), parseFloat-style prefix numeric parsing, null coerces to 'null', user_id resolved with ??-style null-only fallback, and a user context lacking a usable id serves only 100% rollouts (ADR-008). See DECISIONS.md ADR-013. When you change one copy, change the other and run both suites.",
+  "rule_match": [
+    {"name": "boolean true matches lowercase 'true'", "rule": {"attribute": "is_beta", "operator": "equals", "value": "true"}, "context": {"is_beta": true}, "expected": true},
+    {"name": "boolean false matches lowercase 'false'", "rule": {"attribute": "is_beta", "operator": "equals", "value": "false"}, "context": {"is_beta": false}, "expected": true},
+    {"name": "boolean true does not match 'True' (no Python-style capitalization)", "rule": {"attribute": "is_beta", "operator": "equals", "value": "True"}, "context": {"is_beta": true}, "expected": false},
+    {"name": "boolean true not_equals 'false'", "rule": {"attribute": "is_beta", "operator": "not_equals", "value": "false"}, "context": {"is_beta": true}, "expected": true},
+    {"name": "integer-valued float coerces without trailing .0", "rule": {"attribute": "price", "operator": "equals", "value": "42"}, "context": {"price": 42.0}, "expected": true},
+    {"name": "null context value coerces to the string 'null'", "rule": {"attribute": "ref", "operator": "equals", "value": "null"}, "context": {"ref": null}, "expected": true},
+    {"name": "absent attribute never matches", "rule": {"attribute": "missing", "operator": "equals", "value": "x"}, "context": {"other": "x"}, "expected": false},
+    {"name": "contains substring", "rule": {"attribute": "email", "operator": "contains", "value": "company"}, "context": {"email": "a@company.com"}, "expected": true},
+    {"name": "ends_with suffix", "rule": {"attribute": "email", "operator": "ends_with", "value": "@company.com"}, "context": {"email": "a@company.com"}, "expected": true},
+    {"name": "gt with non-numeric suffix (parseFloat prefix parse)", "rule": {"attribute": "age", "operator": "gt", "value": "18"}, "context": {"age": "25px"}, "expected": true},
+    {"name": "gt prefix parse below threshold", "rule": {"attribute": "v", "operator": "gt", "value": "18"}, "context": {"v": "5px"}, "expected": false},
+    {"name": "gt with fully non-numeric string is NaN -> false", "rule": {"attribute": "v", "operator": "gt", "value": "1"}, "context": {"v": "abc"}, "expected": false},
+    {"name": "gt with boolean context is NaN -> false (parseFloat('true'))", "rule": {"attribute": "flag", "operator": "gt", "value": "0"}, "context": {"flag": true}, "expected": false},
+    {"name": "lt numeric", "rule": {"attribute": "age", "operator": "lt", "value": "18"}, "context": {"age": "5"}, "expected": true},
+    {"name": "in_list string member matches", "rule": {"attribute": "country", "operator": "in_list", "value": ["US", "CA", "UK"]}, "context": {"country": "US"}, "expected": true},
+    {"name": "in_list stringified number does not match raw number item (shared footgun)", "rule": {"attribute": "n", "operator": "in_list", "value": [42]}, "context": {"n": 42}, "expected": false},
+    {"name": "in_list stringified number matches string item", "rule": {"attribute": "n", "operator": "in_list", "value": ["42"]}, "context": {"n": 42}, "expected": true}
+  ],
+  "evaluate": [
+    {"name": "disabled flag returns default", "flag_key": "f", "flag": {"enabled": false, "rollout_pct": 100, "flag_type": "boolean", "default_value": "off", "rules": []}, "user": {"user_id": "1"}, "expected": "off"},
+    {"name": "no user context, rollout 100 -> enabled", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 100, "flag_type": "boolean", "default_value": false, "rules": []}, "user": null, "expected": true},
+    {"name": "no user context, rollout 50 -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 50, "flag_type": "boolean", "default_value": false, "rules": []}, "user": null, "expected": false},
+    {"name": "rule match beats rollout 0", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"attribute": "plan", "operator": "equals", "value": "pro"}]}, "user": {"plan": "pro"}, "expected": true},
+    {"name": "boolean-coercion rule matches end to end", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"attribute": "is_beta", "operator": "equals", "value": "true"}]}, "user": {"is_beta": true}, "expected": true},
+    {"name": "has user_id, rollout 0, no match -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"user_id": "x"}, "expected": false},
+    {"name": "user context without id, rollout 100 -> enabled (ADR-008)", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 100, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"plan": "pro"}, "expected": true},
+    {"name": "user context without id, rollout 50 -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 50, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"plan": "pro"}, "expected": false},
+    {"name": "empty-string user_id is treated as present (rollout 100)", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 100, "flag_type": "boolean", "default_value": false, "rules": []}, "user": {"user_id": "", "id": "ignored"}, "expected": true}
+  ]
+}

{switchbox_flags-0.2.0 → switchbox_flags-0.3.0}/tests/test_client.py

@@ -1,7 +1,10 @@
 import json
 from unittest.mock import MagicMock, patch
 
-from switchbox.client import Client
+from switchbox.client import Switchbox
+
+TEST_SDK_KEY = "dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM"
+TEST_CDN = "https://example.com"
 
 SAMPLE_CONFIG = {
     "version": "2026-04-07T12:00:00Z",
@@ -36,21 +39,21 @@ def _mock_urlopen(data):
 @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(sdk_key="dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM", cdn_base_url="https://example.com") as client:
+    with Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN) 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(sdk_key="dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM", cdn_base_url="https://example.com") as client:
+    with Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN) 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(sdk_key="dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM", cdn_base_url="https://example.com") as client:
+    with Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN) as client:
         assert client.enabled("new_dashboard", user={"user_id": "1"}) is True
         assert client.get_value("search_version", user={"user_id": "1"}) == "v1"
 
@@ -58,7 +61,7 @@ def test_client_works_with_mock_cdn(mock_urlopen):
 @patch("switchbox.sync.urllib.request.urlopen")
 def test_client_handles_cdn_failure_gracefully(mock_urlopen):
     mock_urlopen.side_effect = Exception("Network error")
-    with Client(sdk_key="dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM", cdn_base_url="https://example.com") as client:
+    with Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN) as client:
         # Should return safe defaults, not crash
         assert client.enabled("new_dashboard") is False
         assert client.get_value("search_version", default="v1") == "v1"
@@ -67,7 +70,7 @@ def test_client_handles_cdn_failure_gracefully(mock_urlopen):
 @patch("switchbox.sync.urllib.request.urlopen")
 def test_client_get_all_flags_empty_when_no_flags(mock_urlopen):
     mock_urlopen.return_value = _mock_urlopen({"version": "v1", "flags": {}})
-    with Client(sdk_key="dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM", cdn_base_url="https://example.com") as client:
+    with Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN) as client:
         assert client.get_all_flags() == {}
 
 
@@ -78,7 +81,7 @@ def test_client_handles_invalid_json(mock_urlopen):
     resp.__enter__ = lambda s: s
     resp.__exit__ = MagicMock(return_value=False)
     mock_urlopen.return_value = resp
-    with Client(sdk_key="dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM", cdn_base_url="https://example.com") as client:
+    with Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN) as client:
         assert client.enabled("any_flag") is False
 
 
@@ -86,7 +89,7 @@ def test_client_handles_invalid_json(mock_urlopen):
 def test_client_handles_404(mock_urlopen):
     from urllib.error import HTTPError
     mock_urlopen.side_effect = HTTPError("https://example.com", 404, "Not Found", {}, None)
-    with Client(sdk_key="dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM", cdn_base_url="https://example.com") as client:
+    with Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN) as client:
         assert client.enabled("any") is False
 
 
@@ -94,7 +97,7 @@ def test_client_handles_404(mock_urlopen):
 def test_client_handles_500(mock_urlopen):
     from urllib.error import HTTPError
     mock_urlopen.side_effect = HTTPError("https://example.com", 500, "Server Error", {}, None)
-    with Client(sdk_key="dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM", cdn_base_url="https://example.com") as client:
+    with Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN) as client:
         assert client.enabled("any") is False
 
 
@@ -102,7 +105,7 @@ def test_client_handles_500(mock_urlopen):
 def test_client_handles_timeout(mock_urlopen):
     from urllib.error import URLError
     mock_urlopen.side_effect = URLError("timed out")
-    with Client(sdk_key="dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM", cdn_base_url="https://example.com") as client:
+    with Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN) as client:
         assert client.enabled("any") is False
 
 
@@ -111,7 +114,7 @@ def test_client_keeps_cached_data_after_failure(mock_urlopen):
     """First call succeeds, second fails — client should keep using cached data."""
     good_resp = _mock_urlopen(SAMPLE_CONFIG)
     mock_urlopen.return_value = good_resp
-    client = Client(sdk_key="dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM", cdn_base_url="https://example.com", poll_interval=9999)
+    client = Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN, poll_interval=9999)
     assert client.enabled("new_dashboard") is True
 
     # Now simulate failure on next poll
@@ -124,7 +127,7 @@ def test_client_keeps_cached_data_after_failure(mock_urlopen):
 @patch("switchbox.sync.urllib.request.urlopen")
 def test_client_context_manager(mock_urlopen):
     mock_urlopen.return_value = _mock_urlopen(SAMPLE_CONFIG)
-    with Client(sdk_key="dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM", cdn_base_url="https://example.com") as c:
+    with Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN) as c:
         assert c.enabled("new_dashboard") is True
     # After exiting context, sync should be stopped
     assert c._sync._stop_event.is_set()
@@ -133,6 +136,6 @@ def test_client_context_manager(mock_urlopen):
 @patch("switchbox.sync.urllib.request.urlopen")
 def test_client_close_stops_sync(mock_urlopen):
     mock_urlopen.return_value = _mock_urlopen(SAMPLE_CONFIG)
-    c = Client(sdk_key="dGVzdC1rZXktZm9yLXVuaXQtdGVzdHM", cdn_base_url="https://example.com")
+    c = Switchbox(sdk_key=TEST_SDK_KEY, cdn_base_url=TEST_CDN)
     c.close()
     assert c._sync._stop_event.is_set()

switchbox_flags-0.3.0/tests/test_parity_vectors.py

@@ -0,0 +1,55 @@
+"""Runs the shared cross-SDK parity vectors (SEC-4).
+
+`parity_vectors.json` is byte-identical to the copy in switchbox-sdk-js; the JS
+suite runs the same file. Both must stay green so the two SDKs evaluate identical
+inputs identically. See the sdk-parity skill and DECISIONS.md ADR-013.
+"""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from switchbox.evaluator import _match_rule, evaluate
+from switchbox.models import FlagConfig, Rule
+
+_VECTORS = json.loads((Path(__file__).parent / "parity_vectors.json").read_text())
+
+
+def _flag_from(case):
+    """Build a Flag from a vector's CDN-shaped flag dict (reuses the real parser)."""
+    config = FlagConfig.from_dict({"flags": {case["flag_key"]: case["flag"]}})
+    return config.flags[case["flag_key"]]
+
+
+@pytest.mark.parametrize("case", _VECTORS["rule_match"], ids=lambda c: c["name"])
+def test_rule_match_vectors(case):
+    rule = Rule(**case["rule"])
+    assert _match_rule(rule, case["context"]) == case["expected"]
+
+
+@pytest.mark.parametrize("case", _VECTORS["evaluate"], ids=lambda c: c["name"])
+def test_evaluate_vectors(case):
+    assert evaluate(_flag_from(case), case["user"]) == case["expected"]
+
+
+def test_user_id_resolution_ignores_id_when_user_id_present():
+    """Null-only (`??`) fallback: `user_id` wins over `id`, so two contexts with
+    the same user_id but different id must bucket — and therefore resolve —
+    identically. (An empty-string user_id is a real id, not falsy.)"""
+    flag = FlagConfig.from_dict(
+        {
+            "flags": {
+                "f": {
+                    "enabled": True,
+                    "rollout_pct": 50,
+                    "flag_type": "boolean",
+                    "default_value": False,
+                    "rules": [],
+                }
+            }
+        }
+    ).flags["f"]
+    a = evaluate(flag, {"user_id": "stable", "id": "aaa"})
+    b = evaluate(flag, {"user_id": "stable", "id": "bbb"})
+    assert a == b

{switchbox_flags-0.2.0 → switchbox_flags-0.3.0}/uv.lock

@@ -236,7 +236,7 @@ wheels = [
 
 [[package]]
 name = "switchbox-flags"
-version = "0.1.0"
+version = "0.3.0"
 source = { editable = "." }
 
 [package.optional-dependencies]

switchbox_flags-0.2.0/switchbox/__init__.py

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

switchbox_flags-0.2.0/switchbox/evaluator.py

@@ -1,104 +0,0 @@
-"""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
-    """
-    try:
-        # 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
-    except Exception:
-        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 context_value is None:
-        return False
-
-    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