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

{switchbox_flags-0.2.0 → switchbox_flags-0.4.0}/.github/workflows/publish.yml

@@ -13,9 +13,9 @@ jobs:
     runs-on: ubuntu-latest
     environment: pypi
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.14"
 

{switchbox_flags-0.2.0 → switchbox_flags-0.4.0}/.github/workflows/test.yml

@@ -13,9 +13,9 @@ jobs:
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: switchbox-flags
-Version: 0.2.0
+Version: 0.4.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.4.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.4.0}/pyproject.toml

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

switchbox_flags-0.4.0/switchbox/__init__.py

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

{switchbox_flags-0.2.0 → switchbox_flags-0.4.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.4.0/switchbox/evaluator.py

@@ -0,0 +1,157 @@
+"""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, RuleGroup
+
+# 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 rule groups: OR across groups, AND within a group (two-level
+        #    DNF). Any matching group wins.
+        for group in _to_groups(flag.rules):
+            if _match_group(group, 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 _to_groups(rules: list) -> list[RuleGroup]:
+    """Normalise a flag's rules into RuleGroups. ``from_dict`` already yields
+    RuleGroups; this also tolerates a flat list of ``Rule`` (legacy/direct
+    construction) — each becomes its own single-condition group, preserving the
+    old OR semantics. Idempotent."""
+    groups: list[RuleGroup] = []
+    for r in rules:
+        if isinstance(r, RuleGroup):
+            groups.append(r)
+        elif isinstance(r, Rule):
+            groups.append(RuleGroup(conditions=[r]))
+    return groups
+
+
+def _match_group(group: RuleGroup, user_context: dict) -> bool:
+    """A group matches when ALL its conditions match (AND). An empty group
+    matches no one (never 'match all')."""
+    return bool(group.conditions) and all(
+        _match_rule(c, user_context) for c in group.conditions
+    )
+
+
+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.4.0}/switchbox/models.py

@@ -1,14 +1,27 @@
+from __future__ import annotations
+
 from dataclasses import dataclass, field
 from typing import Any
 
 
 @dataclass
 class Rule:
+    """A single condition. The atom of targeting."""
+
     attribute: str
     operator: str  # equals | not_equals | contains | ends_with | in_list | gt | lt
     value: Any
 
 
+@dataclass
+class RuleGroup:
+    """An AND-group of conditions. Groups are OR'd by the evaluator — two-level
+    DNF (ADR-015): a flag matches if any group matches; a group matches if all
+    its conditions match."""
+
+    conditions: list[Rule] = field(default_factory=list)
+
+
 @dataclass
 class Flag:
     key: str
@@ -16,7 +29,20 @@ class Flag:
     rollout_pct: int
     flag_type: str  # boolean | string | number | json
     default_value: Any
-    rules: list[Rule] = field(default_factory=list)
+    rules: list[RuleGroup] = field(default_factory=list)
+
+
+def _parse_condition(d: dict) -> Rule:
+    return Rule(attribute=d["attribute"], operator=d["operator"], value=d["value"])
+
+
+def _parse_rule_group(entry: dict) -> RuleGroup:
+    """Parse one rules entry, accepting the two-level shape
+    ``{"conditions": [...]}`` and the legacy flat ``{attribute, operator, value}``
+    (a pre-DNF config) — the latter becomes a single-condition group."""
+    if "conditions" in entry:
+        return RuleGroup(conditions=[_parse_condition(c) for c in entry["conditions"]])
+    return RuleGroup(conditions=[_parse_condition(entry)])
 
 
 @dataclass
@@ -29,14 +55,7 @@ class 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", [])
-            ]
+            rules = [_parse_rule_group(r) for r in flag_data.get("rules", [])]
             flags[key] = Flag(
                 key=key,
                 enabled=flag_data["enabled"],

{switchbox_flags-0.2.0 → switchbox_flags-0.4.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.4.0/tests/parity_vectors.json

@@ -0,0 +1,39 @@
+{
+  "_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},
+    {"name": "DNF: AND-group with all conditions matching -> enabled", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": [{"attribute": "country", "operator": "equals", "value": "US"}, {"attribute": "device", "operator": "equals", "value": "mobile"}]}]}, "user": {"country": "US", "device": "mobile"}, "expected": true},
+    {"name": "DNF: AND-group with one failing condition -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": [{"attribute": "country", "operator": "equals", "value": "US"}, {"attribute": "device", "operator": "equals", "value": "mobile"}]}]}, "user": {"country": "US", "device": "desktop"}, "expected": false},
+    {"name": "DNF: second group matches (OR across groups) -> enabled", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": [{"attribute": "country", "operator": "equals", "value": "US"}]}, {"conditions": [{"attribute": "plan", "operator": "equals", "value": "ent"}]}]}, "user": {"plan": "ent"}, "expected": true},
+    {"name": "DNF: no group matches (OR across groups) -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": [{"attribute": "country", "operator": "equals", "value": "US"}]}, {"conditions": [{"attribute": "plan", "operator": "equals", "value": "ent"}]}]}, "user": {"plan": "free", "country": "EU"}, "expected": false},
+    {"name": "DNF: empty-conditions group never matches -> default", "flag_key": "f", "flag": {"enabled": true, "rollout_pct": 0, "flag_type": "boolean", "default_value": false, "rules": [{"conditions": []}]}, "user": {"any": "thing"}, "expected": false},
+    {"name": "DNF back-compat: legacy flat rule still matches -> enabled", "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}
+  ]
+}

{switchbox_flags-0.2.0 → switchbox_flags-0.4.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.2.0 → switchbox_flags-0.4.0}/tests/test_models.py

@@ -22,8 +22,9 @@ def test_flag_config_from_dict_valid():
     flag = config.flags["feature_a"]
     assert flag.enabled is True
     assert flag.rollout_pct == 50
+    # Legacy flat rule is parsed into a single-condition group (back-compat).
     assert len(flag.rules) == 1
-    assert flag.rules[0].attribute == "country"
+    assert flag.rules[0].conditions[0].attribute == "country"
 
 
 def test_flag_config_from_dict_missing_fields():
@@ -69,6 +70,31 @@ def test_flag_config_from_dict_with_rules():
     assert len(config.flags["f"].rules) == 2
 
 
+def test_flag_config_from_dict_with_dnf_groups():
+    """The two-level shape: a group with multiple AND'd conditions."""
+    data = {
+        "version": "v1",
+        "flags": {
+            "f": {
+                "enabled": True,
+                "rules": [
+                    {
+                        "conditions": [
+                            {"attribute": "country", "operator": "equals", "value": "US"},
+                            {"attribute": "device", "operator": "equals", "value": "mobile"},
+                        ]
+                    },
+                    {"conditions": [{"attribute": "plan", "operator": "equals", "value": "ent"}]},
+                ],
+            }
+        },
+    }
+    flag = FlagConfig.from_dict(data).flags["f"]
+    assert len(flag.rules) == 2  # two groups (OR)
+    assert len(flag.rules[0].conditions) == 2  # AND within the first group
+    assert flag.rules[1].conditions[0].attribute == "plan"
+
+
 def test_flag_defaults():
     flag = Flag(key="f", enabled=True, rollout_pct=100, flag_type="boolean", default_value=False)
     assert flag.rules == []

switchbox_flags-0.4.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.4.0}/uv.lock

@@ -236,7 +236,7 @@ wheels = [
 
 [[package]]
 name = "switchbox-flags"
-version = "0.1.0"
+version = "0.4.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